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Last Updated: July 7, 2002 


Welcome to the Windows API Guide! Here, you will discover a wealth of information to help you 
implement calls to the Windows API directly from your Visual Basic programs. This site is sort of a 
work in progress; it falls short of encompassing the entire Windows API. Nevertheless, new information 
about functions and the like is added every two or three weeks. Check back often to see what's new! 


feel MaximumASP 
The New Guru Is Here! Semen 





Hello fellow programmers! I'm Chris Pietschmann, and I will be updating this site from now on. There 
isn't anything new yet, but I'm working on a new format for the site. All the old stuff will remain in the 
old look, and Only new stuff will have the new look. But I will still update the old stuff. 


Reference 


The Reference section contains documentation on hundreds of Windows API functions. Besides the 
functions, information on the related structures and other items also appears for reference. Each function 
page includes a well-commented example illustrating common usage of the function. 


Articles 


The Articles section contains articles about API-related topics. These multi-page articles go in-depth 
about a specific issue in the API and offer a more well-rounded approach to learning about API functions 
without much technical information. Of course, the reference information for each function is only a 
click away. 


Still can't find what you're looking for anywhere on the site? Then try browsing the VB-World.net web 
site. Along with their sizable collection of Visual Basic programming information, they also have an API 
programming section filled with helpful articles, some of which cover ideas not currently discussed on 
this web site. 
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Still unable to find what you're looking for? You might want to e-mail me about what you're looking for. 
If I can't give you the information, I might be able to point you in the right direction anyway. 


Awards the Windows API Guide has won: 





Web Directory 


Last Modified: March 7, 2002 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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Windows API Reference 


Last Update: March 2, 2001 


Important Message 

I, Paul Kuliniewicz, am no longer able to continue maintaining this web site. There will be no more 
updates to this site unless some other party takes over operation. Please read my farewell message for all 
the details and other information for loyal visitors. 


Welcome to the Reference section of the Windows API Guide. Here, you will find documentation on 
hundreds of API functions and the structures that go along with them. Each API function page includes 
an example in Visual Basic 5.0 which demonstrates proper usage. The information in the reference 
section is organized according to what it describes. Please click on a link below. 


Interested in what has been added or edited since the last update of the Windows API Guide? Take a look 
at the Revision History of the Reference section! 


January 21, 2001: A smaller update than usual. The examples on all the Winsock functions have been 
fixed. The old code could hang if the remote server would stop responding. That bug has been corrected 
via the ioctlsocket function. Some list box messages have also been added, a function or two that work 





with screen resolutions, and a number of various error fixes. Sadly, problems with the server prevented 
me from getting the new search engine ready for this update. It should be up and running next time. 
Speaking of which, there will be some revisions in the overall layout of the site, which will hopefully aid 
navigation. Be warned: any bookmarks that point to anything that isn't http://www.vbapi.com/ will 


probably break, so be prepared. 


e Function Information: (357 functions listed, 4 newly added) 
o Alphabetical Listin 


o Categorical Listin 


e Structure Information: (83 structures listed) 
o Alphabetical Listin 
e Message Information: (66 messages listed, 6 newly added) 
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o Alphabetical Listing 
o Categorical Listin 
e Callback Function Information: (15 callback functions listed) 
o Alphabetical Listin 
e Macro Information: (15 macros listed) 
o Alphabetical Listin 
e Other Reference Information 


e API Glossary 


Go back to the Windows API Guide home page. 


Last Modified: March 2, 2001 

This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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Windows API Reference: Revision 
History 


The following list identifies which pages have been added or significantly changed in each update of the 
Windows API Guide's Reference section since February 13, 2000. Added or edited pages are listed 
according to date and general description (1.e., function pages are grouped together, etc.). Any page that 
was added in the update is flagged with NEW. Any page that was edited significantly (such as a 
correction or a layout change) appears in normal text. 


January 21, 2001 Update 


January 21, 2001: A smaller update than usual. The examples on all the Winsock functions have been 


fixed. The old code could hang if the remote server would stop responding. That bug has been corrected 
via the ioctlsocket function. Some list box messages have also been added, a function or two that work 


with screen resolutions, and a number of various error fixes. Sadly, problems with the server prevented 
me from getting the new search engine ready for this update. It should be up and running next time. 
Speaking of which, there will be some revisions in the overall layout of the site, which will hopefully aid 
navigation. Be warned: any bookmarks that point to anything that isn't http://www.vbapi.com/ will 
probably break, so be prepared. 


e Functions: 


o ChangeDisplaySettings NEW 
o ClosePrinter 


o closesocket 

o connect 

o EnumDisplaySettings NEW 
o GetProfileInt 

o htons 

o 1octlsocket NEW 

o OpenPrinter 

o PrinterProperties NEW 

o recy 
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O 


O 


O 


O 


O 


RegQuery ValueEx 


send 
SetFilePointer 


SHGetSpecialFolderLocation 
socket 


e Structures: 


O 


DEVMODE 


e Messages: 


LB_GETCURSEL NEW 
LB_GETSEL NEW 
LB_GETSELCOUNT NEW 
LB_GETSELITEMS NEW 
LB_SETCURSEL NEW 
LB_SETSEL NEW 


e Other: 


O 


Extended Window Styles 


December 17, 2000 Update 


December 17, 2000: Some more Winsock functions have been added, along with a few list box 
messages. I've also corrected a few minor mistakes on some pages, but I haven't yet been able to fix all 
the mistakes I've been notified of yet. Hopefully those will be done in time for the next update. Finally, 
I'm still working on the search engine for the site. Most of it is done, but it still needs some more testing 


and security checking before I add it to the site. 


e Functions: 


closesocket NEW 
connect NEW 
DestroyWindow 
FindWindow 
FindWindowEx 
GetFocus NEW 
GetSaveFileName 
htonl 

htons NEW 
KillTimer 
LockWorkStation NEW 
recv NEW 
RemoveMenu NEW 
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o send NEW 

o SetFocus NEW 
o SetTimer 

o SHFileOperation 
o socket NEW 


e Structures: 
o HOSTENT 


o SOCKADDR NEW 


e Messages: 
o EM_GETPASSWORDCHAR 


o LB_ADDSTRING NEW 

o LB_DELETESTRING NEW 
o LB_GETCOUNT NEW 

o LB_GETTEXT NEW 

o LB_GETTEXTLEN NEW 

o LB_INSERTSTRING NEW 

o LB_RESETCONTENT NEW 
o WM_CLOSE NEW 

o WM_TIMER 


October 29, 2000 Update 


October 29, 2000: I've finally added a few Winsock API functions, at popular request. Also making an 
appearance are the CreateWindowEx function and information about the IP Address control. Finally, I've 
moved window class information into its own small section. 


e Functions: 
o CreateWindowEx NEW 
o DestroyWindow NEW 


o GetClassLong 
o gethostbyaddr NEW 


o gethostbyname NEW 
o gethostname NEW 


o GetWindowLong 

o htonl NEW 

o inet_addr NEW 

o inet_ntoa NEW 

o InitCommonControlsEx NEW 
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o SendInput 
o SetWindowLong 
o WSACleanup NEW 
o WSAGetLastError NEW 
o WSAStartup NEW 
e Structures: 
o ENUMLOGFONTEX 
o HOSTENT NEW 
o INITCOMMONCONTROLSEX_TYPE NEW 
o WSADATA NEW 
e Messages: 
o BM_CLICK 
o IPM _CLEARADDRESS NEW 
o IPM_GETADDRESS NEW 
o IPM _ISBLANK NEW 
o IPM_SETADDRESS NEW 
o IPM_SETFOCUS NEW 
o IPM_SETRANGE NEW 
e Macros: 
o FIRST_IPADDRESS NEW 
o FOURTH IPADDRESS NEW 
o HIBYTE NEW 
o LOBYTE NEW 
o MAKEIPRANGE NEW 
o MAKELANGID 
o MAKEWORD NEW 
o SECOND _IPADDRESS NEW 
o THIRD IPADDRESS NEW 
e Window Classes: 
o Base Window Styles NEW 
o Button Control Window Class NEW 
o Combo Box Control Window Class NEW 
o Edit Control Window Class NEW 
o Extended Window Styles NEW 
o IP Address Control Window Class NEW 
o List Box Control Window Class NEW 
o Scroll Bar Control Window Class NEW 
o Static Control Window Class NEW 
e Other: 
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o Winsock error codes NEW 


September 24, 2000 Update 


September 24, 2000: Starting today, I'm going to write a short message like this in each update. For all 
of you who've asked me about how to get a list of the currently running processes on the system, your 
prayers have been answered. At least, the prayers about getting a list of processes on the system... 
Anyway, you'll want to look at CreateToolhelp32Snapshot for that. I also added, among other things, 
SetWindowRgn, needed to make nonrectangular-looking windows. For the complete list of new goodies, 


go to the history page. 


e Functions: 
o CreateToolhelp32Snapshot NEW 
o GetDiskFreeSpaceEx 


o GetOpenFileName 
o GetSaveFileName 


o GetSysColor NEW 

o GetWindowRgn NEW 
o Process32First NEW 
o Process32Next NEW 


o RegDeleteKey 


o RegEnumValue 
o SetSysColors NEW 


o SetWindowRgn NEW 
e Structures: 

o OPENFILENAME 

o PROCESSENTRY32 NEW 
e Messages: 

o CB_ADDSTRING NEW 

o CB_DELETESTRING NEW 

o CB_INSERTSTRING NEW 

o CB_RESETCONTENT NEW 
e Callback Functions: 

o OFNHookProc NEW 

o OFNHookProcOldStyle NEW 


August 26, 2000 Update 
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e Functions: 


o GetCapture 
o GetEnvironmentVariable NEW 


o mouse_event 


o QueryPerformanceCounter NEW 
o QueryPerformanceFrequency NEW 


o SendInput 
o SetEnvironmentVariable NEW 


o ShellExecute 
o ShellExecuteEx NEW 
o WaitForSingleObject NEW 


e Structures: 
o ITEMIDLIST 
o JOB _INFO_ 1 
o LARGE INTEGER NEW 
o LOGFONT 
o SHELLEXECUTEINFO NEW 
e Messages: 
o EM_CANUNDO NEW 
o EM_GETFIRSTVISIBLELINE NEW 
o EM_GETLINE NEW 
o EM_LINEINDEX NEW 
o EM_LINELENGTH NEW 
o EM_UNDO NEW 
e MCI Commands: 
o open 


July 30, 2000 Update 


e Functions: 
o EqualRgen 


o GetAsyncKeyState 
o GetFileVersionInfo NEW 


o GetFileVersionInfoSize NEW 
o GetKeyState 

o RegCloseKey 

o RegCreateKeyEx 

o RegisterClassEx 
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o RegQueryValueEx 


o SetTimer 


o VerQueryValue NEW 


e Structures: 
o VS _FIXEDFILEINFO NEW 


e Messages: 
o BM_CLICK NEW 


o BM _GETCHECK NEW 
o BM_GETSTATE NEW 
o BM_SETCHECK NEW 
o BM_SETSTATE NEW 
e Macros: 

o GET_X LPARAM 

o GET_Y_LPARAM 

o HIWORD 

o LOWORD 


July 4, 2000 Update 


e Functions: 


o ExitWindowsDialog NEW 
o GetShortPathName 


o mciGetErrorString NEW 
o mciSendString NEW 
o RestartDialog NEW 


e Messages: 
o MM_MCINOTIFY NEW 


e MCI Command Strings: 
o close NEW 
o open NEW 
o pause NEW 
o play NEW 
o stop NEW 


June 4, 2000 Update 


e Functions: 
o CreatePopupMenu NEW 
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o DestroyMenu NEW 

o GetMenu NEW 

o GetMenultemCount NEW 
o GetMenultemInfo NEW 
o GetSystemMenu NEW 

o GetVolumelInformation 

o InsertMenultem NEW 

o PickIconDlg NEW 

o SetMenultemInfo NEW 


o TrackPopupMenu NEW 

o TrackPopupMenuEx NEW 
e Structures: 

o MENUITEMINFO NEW 

o RECT 

o TPMPARAMS NEW 
e Messages: 

o WM_COMMAND NEW 

o WM_INITMENU NEW 

o WM_SYSCOMMAND NEW 
e Macros: 

o HIWORD NEW 

o LOWORD NEW 


May 21, 2000 Update 


e Functions: 
o GetCapture NEW 
o KillTimer NEW 
o RegEnumValue 
o ReleaseCapture NEW 
o SetCapture NEW 
o SetTimer NEW 
o SHFileOperation 
e Messages: 
o EM_GETPASSWORDCHAR NEW 
o EM_GETSEL NEW 
o EM _REPLACESEL NEW 
o EM_SETPASSWORDCHAR NEW 
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O 


O 


EM_SETSEL NEW 
WM_TIMER NEW 


e Callback Functions: 


O 


TimerProc NEW 


e Macros: 


O 


MAKELANGID 


April 16, 2000 Update 


e Functions: 


O 


GetCurrencyFormat NEW 
GetNumberFormat NEW 
GetVolumelnformation NEW 
RoundRect 

SetVolumeLabel NEW 
SHFileOperation NEW 


SHFreeNameMappings NEW 


e Structures: 


O 


O 


O 


O 


O 


CURRENCYFMT NEW 
MEMORYSTATUSEX 
NUMBERFMT NEW 
SHFILEOPSTRUCT NEW 
SHNAMEMAPPING NEW 


e Messages: 


CB_GETCOUNT NEW 
CB_GETCURSEL NEW 
CB_GETDROPPEDSTATE NEW 
CB_GETLBTEXT NEW 
CB_GETLBTEXTLEN NEW 
CB_SETCURSEL NEW 
CB_SHOWDROPDOWN NEW 


e Macros: 


O 


MAKELCID NEW 


March 19, 2000 Update 


e Functions: 
o CreateDirecto 
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o CreateDirectoryEx 

o GetAsyncKeyState 

o GetDiskFreeSpaceEx 

o GetTickCount NEW 

o GlobalMemoryStatus NEW 

o GlobalMemoryStatusEx NEW 
o RegEnumKeyEx 


o SendInput 
o Shell NotifyIcon NEW 


e Structures: 
o MEMORYSTATUS NEW 
o MEMORYSTATUSEX NEW 
o NOTIFYICONDATA NEW 
o POINT_TYPE 
o ULARGE_INTEGER 
e Messages: 
o WM _LBUTTONDBLCLK NEW 
o WM_LBUTTONDOWN NEW 
o WM_LBUTTONUP NEW 
o WM MBUTTONDBLCLK NEW 
o WM_MBUTTONDOWN NEW 
o WM_MBUTTONUP NEW 
o WM _MOUSEMOVE NEW 
o WM_RBUTTONDBLCLK NEW 
o WM_RBUTTONDOWN NEW 
o WM _RBUTTONUP NEW 
e Macros: 
o GET_X_ LPARAM NEW 
o GET_Y_LPARAM NEW 
o MAKELANGID 
o MAKEPOINTS NEW 
e Other: 
o Error Codes 


February 13, 2000 Update 


e Functions: 
o GetWindowText 
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o GetWindowTextLength 
o MessageBox NEW 


o MessageBoxEx NEW 
o MessageBoxIndirect NEW 
o SetWindowText 
e Structures: 
o HELPINFO NEW 
o MSGBOXPARAMS NEW 
e Messages: 
o WM_GETTEXT NEW 
o WM_GETTEXTLENGTH NEW 
o WM_HELP NEW 
o WM_SETTEXT NEW 
e Callback Functions: 
o MsgBoxCallback NEW 


e Macros: 
o MAKELANGID NEW 


Go back to the Reference section index. 


Last Modified: January 21, 2001 

This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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Windows API Reference: Functions 


Last Update: January 21, 2001 
Number of Functions Listed: 357 (4 added) 


Below is an alphabetical list of the API functions currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to: AIBICIDIEIFIGIHIIIJIKILIMINIOIPIQIRISITIUIVIWIXIYIZ 


o AngleArc 
o Arc 


o ArcTo 

o auxGetDevCaps 
o auxGetNumDevs 
o auxGetVolume 
o auxSetVolume 


o Beep 
o BitBlt 


o BringWindowToTop 


o CallWindowProc 


o ChangeDisplaySettings NEW 
o CharLower 


o CharUpper 
o ChooseColor 


o ChooseFont 
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o Chord 

o ClipCursor 
o CloseHandle 
o ClosePrinter 
o closesocket 


o CombineRgn 

o CommD]1gExtendedError 
o CompareFileTime 

o CompareString 

o connect 

o CopyFile 

o CopyMemory 


o CopyRect 
o CoTaskMemFree 


o CreateCursor 
o CreateDC 


o CreateDirectory 
o CreateDirectoryEx 
o CreateEllipticRgn 


o CreateEllipticRgnIndirect 
o CreateFile 


o CreateFont 
o CreateFontIndirect 
o CreateHatchBrush 
o CreatePen 
o CreatePenIndirect 


o CreatePolygonRgn 

o CreatePolyPolygonRgn 
o CreatePopupMenu 

o CreateRectRgn 

o CreateRectRgnIndirect 
o CreateRoundRectRgn 
o CreateSolidBrush 


o CreateToolhelp32Snapshot 
o CreateWindowEx 


o DefWindowProc 
o DeleteDC 
o DeleteFile 


http://216.26.168.92/vbapi/ref/funca.html (2 of 11) [9/1/2002 5:00:52 PM] 


Windows API Guide: Reference: Functions 


o DeleteObject 
o DestroyCursor 
o DestroylIcon 
o DestroyMenu 


o DestroyWindow 
o Drawlcon 


o DrawlIconEx 


o Ellipse 
o EnableWindow 
o EndDoc 


o EndPage 
o EnumChildWindows 


o EnumDisplaySettings NEW 
o EnumFontFamilies 

o EnumFontFamiliesEx 

o EnumJobs 

o EnumPrinters 

o EnumPropsEx 

o EnumThreadWindows 

o EnumWindows 


o EqualRect 
o EqualRgn 


o ExitWindowsDialog 
o ExitWindowsEx 


o ExtFloodFill 
o ExtractIcon 
o ExtractIconEx 


o FileTimeToLocalFileTime 


o FileTimeToSystemTime 
o FillMemory 

o FillRect 

o FillRgn 

o FindClose 

o FindFirstFile 

o FindNextFile 

o FindWindow 

o FindWindowEx 
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o FlashWindow 
o FrameRect 


o FrameRgn 


o GetActiveWindow 
o GetArcDirection 


o GetAsyncKeyState 
o GetBrushOrgEx 


o GetCapture 
o GetClassInfo 


o GetClassInfoEx 

o GetClassLong 

o GetClassName 

o GetClipCursor 

o GetComputerName 


o GetCurrencyFormat 
o GetCursor 


o GetCursorPos 
o GetDateFormat 
o GetDC 


o GetDesktopWindow 

o GetDiskFreeSpace 

o GetDiskFreeSpaceEx 

o GetDoubleClickTime 

o GetDriveType 

o GetEnvironmentVariable 
o GetFileAttributes 

o GetFileInformationByHandle 
o GetFileSize 

o GetFileTime 

o GetFileVersionInfo 

o GetFileVersionInfoSize 
o GetFocus 

o GetForegroundWindow 
o GetFullPathName 

o gethostbyaddr 

o gethostbyname 

o gethostname 

o GetKeyboardState 
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o GetKeyState 
o GetLastError 


o GetLocalTime 


o GetLogicalDrives 


o GetLogicalDriveStrings 
o GetMenu 


o GetMenultemCount 
o GetMenultemInfo 
o GetNumberFormat 
o GetOpenFileName 
o GetParent 

o GetPixel 


o GetPolyFillMode 
o GetPrivateProfilelnt 


o GetPrivateProfileString 
o GetProfileInt 

o GetProfileString 

o GetProp 


o GetRgnBox 
o GetSaveFileName 


o GetShortPathName 


o GetStockObject 

o GetSysColor 

o GetSystemDirectory 

o GetSystemMenu 

o GetSystemMetrics 

o GetSystemTime 

o GetSystemTimeAsFileTime 
o GetTempFileName 

o GetTempPath 


o GetTextAlign 
o GetThreadLocale 


o GetTickCount 

o GetTimeFormat 

o GetTimeZonelInformation 
o GetTopWindow 

o GetUserName 

o GetVersionEx 
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o GetVolumelInformation 
o GetWindow 

o GetWindowLong 

o GetWindowRect 

o GetWindowsDirectory 
o GetWindowRgn 

o GetWindowText 

o GetWindowTextLength 
o GetWindowThreadProcessId 
o GlobalAlloc 

o GlobalFree 

o GlobalLock 


o GlobalMemoryStatus 


o GlobalMemoryStatusEx 
o GlobalUnlock 


e H 
o htonl 
o htons 
e I 
o inet_addr 
o inet_ntoa 


o InflateRect 

o InitCommonControlsEx 
o InsertMenultem 
o IntersectRect 

o InvertRect 

o InvertRgn 

o 1octlsocket NEW 
o IsChild 

o IsIconic 

o IsRectEmpty 

o IsWindow 

o IsWindowEnabled 
o IsZoomed 


o joyGetDevCaps 
o joyGetNumDevs 


o joyGetPos 
e K 
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o keybd_event 
o KillTimer 


o LineTo 

o LoadCursor 

o LoadCursorFromFile 

o LocalFileTimeToFileTime 
o LockWorkStation 


o Istrcmp 
o Istrcmpi 
o Istrcpy 


o Istrcpyn 
o Istrlen 


o mciGetErrorString 
o mciSendString 

o MessageBeep 

o MessageBox 

o MessageBoxEx 


o MessageBoxIndirect 
o mouse event 


o MoveFile 

o MoveMemory 
o MoveToEx 

o MoveWindow 
o MulDiv 


O zZz 


o OffsetRect 


o OffsetRgn 
o OpenPrinter 


o PickIconDlg 
o Pie 

o PlaySound 

o PolyBezier 
o PolyBezierTo 
o Polygon 

o Polyline 
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o PolylineTo 

o PolyPolygon 

o PolyPolyline 

o PrintDlg 

o PrinterProperties NEW 
o Process32First 

o Process32Next 

o PtInRect 


o PtInRegion 


o QueryPerformanceCounter 
o QueryPerformanceFrequency 


o ReadFile 


o Rectangle 

o RectInRegion 

o recy 

o RegCloseKey 

o RegCreateKeyEx 
o RegDeleteKey 

o RegDeleteValue 
o RegEnumKeyEx 
o RegEnumValue 
o RegisterClass 

o RegisterClassEx 
o RegOpenKeyEx 
o RegQueryValueEx 
o RegSetValueEx 
o ReleaseCapture 
o ReleaseDC 


o RemoveDirectory 
o RemoveMenu 
o RemoveProp 


o RestartDialog 
o RoundRect 


o SelectObject 
o send 


o SendInput 
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o SendMessage 
o SetActiveWindow 


o SetArcDirection 


o SetBrushOrgEx 
o SetCapture 


o SetClassLong 
o SetCursor 


o SetCursorPos 

o SetDoubleClickTime 

o SetEnvironmentVariable 
o SetFileAttributes 

o SetFilePointer 

o SetFileTime 

o SetFocus 


o SetForegroundWindow 


o SetKeyboardState 
o SetLastError 


o SetLastErrorEx 
o SetMenultemInfo 
o SetParent 

o SetPixel 

o SetPixelV 


o SetPolyFillMode 
o SetProp 

o SetRect 

o SetRectEmpty 

o SetSysColors 

o SetSystemCursor 
o SetSystemTime 


o SetTextAlign 
o SetThreadLocale 


o SetTimer 

o SetVolumeLabel 

o SetWindowLong 

o SetWindowPos 

o SetWindowRgn 

o SetWindowText 

o SHAddToRecentDocs 
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o SHBrowseForFolder 
o Shell_ NotifyIcon 

o ShellExecute 

o ShellExecuteEx 

o SHEmptyRecycleBin 
o SHFileOperation 


o SHFreeNameMappings 
o SHGetFileInfo 


o SHGetFolderLocation 
o SHGetFolderPath 
o SHGetPathFromIDList 


o SHGetSpecialFolderLocation 


o SHGetSpecialFolderPath 
o ShowCursor 


o ShowWindow 

o SHQueryRecycleBin 

o SHUpdateRecycleBinIcon 
o Sleep 


o sndPlaySound 
o socket 


o StartDoc 


o StartPage 
o StretchBlt 


o SubtractRect 


o SwapMouseButton 
o SystemParametersInfo 
o SystemTimeToFileTime 


o TextOut 


o TrackPopupMenu 
o TrackPopupMenuEx 


o UnionRect 
o UnregisterClass 


o VerQuery Value 


o WaitForSingleObject 
o waveOutGetDevCaps 
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o waveOutGetNumDevs 

o waveOutGetVolume 

o waveOutSetVolume 

o WindowFromPoint 

o WinHelp 

o WriteFile 

o WritePrivateProfileS tring 
o WriteProfileString 

o WSACleanup 

o WSAGetLastError 


o WSAStartup 


eee 
N< 


o ZeroMemory 


Go back to the Reference section index. 
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This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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AngleArc Function 


Declare Function AngleArc Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal x As Long, 
ByVal y As Long, ByVal dwRadius As Long, ByVal eStartAngle As Single, ByVal 
eSweepAngle As Single) As Long 














Platforms 


Windows 95: Not Supported 

Windows 98: Not Supported 

Windows NT: Requires Windows NT 3.1 or greater 
Windows 2000: Supported 

Windows CE: Not Supported 


Description & Usage 


AngleArc draws a circular arc on a device using the device's current pen. The circle which the arc lies on is determined by 
its center and radius. The start and end points of the arc are determined by angle measures in degrees, measured 
counterclockwise from the line parallel to the positive x-axis (i.e., from due right). The arc itself is drawn either clockwise 
or counterclockwise to connect the points, depending on the device's settings. AngleArc also draws a line connecting the 
device's current point to the beginning of the arc. 


Return Value 


If an error occurs, the function returns O (call GetLastError to get the error code). If the function succeeds, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None 


Parameters 


hdc 
A handle to a device context of the device to draw the arc on. 


The x coordinate of the center of the circle. 


The y coordinate of the center of the circle. 
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dwRadius 


The radius of the circle. 
eStartAngle 
The angle (in degrees) identifying the starting point of the arc. 
eSweepAngle 
The angle (in degrees) identifying the ending point of the arc. 


Example 


' This code is licensed according to the terms and conditions 





' Draw an arc formed by the upper half of a circle (from 0 to 180 


' degrees counterclockwise). 


' of 50 





Dim ret 





The circle is centered at (100, 150) 


. The arc is drawn using the solid black stock pen. 


Dim hpen As Long ' handle to the black stock pen 
Dim holdpen As Long ' handle to Forml's previously selected pen 





val As Long ' return value 





" Get t 
hpen = 
holdpen 


' Make 
retval 





' Draw 
retval 





' Selec 
retval 


he solid black stock pen and select it for use in Forml. 
GetStockObject (BLACK_PEN) 











= SelectObject (Forml.h 








DC 





" get the pen's handle 
, hpen) " select the pen 


sure arcs are drawn going counterclockwise 


= SetArcl 





Direction (Forml 





the arc 








-h 











DC, AD_COUNTERCLOCKWISE) 





= AngleArc(Forml.hDC, 100, 150, 50, 0, 180) 





t Forml's previous pen to restore the "defaults". 





= SelectObject (Forml.h 








See Also 


DC, 


holdpen) " select the old pen 


Arc, ArcTo, Ellipse, GetArcDirection, SetArcDirection 


Category 


Lines & Curves 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Arc Function 








Declare Function Arc Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal nhLeftRect As Long, 
ByVal nTopRect As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long, ByVal 
nXStartArc As Long, ByVal nYStartArc As Long, ByVal nXEndArc As Long, ByVal nYEndArc 
As Long) As Long 






































Platforms 


Windows 95: Supported 

Windows 98: Supported 

Windows NT: Requires Windows NT 3.1 or later 
Windows 2000: Supported 

Windows CE: Not Supported 


Description & Usage 





Arc draws an elliptical arc on a device using the device's current pen. The ellipse which the arc lies on is inscribed within the 
bounding rectangle coordinates passed to the function. The start and end points are determined by two radials. The radials 
begin at the center of the ellipse and extend through the given radial point (either the start or end one); where they intersect the 
ellipse is where the start and end points of the arc are. Windows 95/98: The arc is always drawn counterclockwise from the 
start point to the end point. Windows NT/2000: The direction the arc is drawn in depends on the device's current setting. 


Return Value 


If an error occured while attempting to draw the arc, the function returns 0 (Win NT/2000: call GetLastError to get the errror 
code). If the function completed successfully, it returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 

A handle to a device context of the device to draw the arc on. 
nLeftRect 

The x coordinate of the upper-left point of the ellipse's bounding rectangle. 
nTopRect 

The y coordinate of the upper-left point of the ellipse's bounding rectangle. 
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nRightRect 

The x coordinate of the lower-right point of the ellipse's bounding rectangle. 
nBottomRect 

The y coordinate of the lower-right point of the ellipse's bounding rectangle. 
nXStartArc 

The x coordinate of the radial point that determines the arc's starting point. 
nYStartArc 

The y coordinate of the radial point that determines the arc's starting point. 
nXEndArc 

The x coordinate of the radial point that determines the arc's ending point. 
nYEndArc 

The y coordinate of the radial point that determines the arc's ending point. 


Example 


' This code is licensed according to the terms and conditions listed here. 























' Draw the arc that forms the top half of an ellipse. The ellipse 

' is centered at (100, 100), has a width of 200, and has a height of 100. The arc is 
drawn 

' on window Forml using the black solid stock pen. 











Dim hpen As Long ' handle to the black solid pen 
Dim holdpen As Long ' handle to window Forml's previously selected pen 
Dim retval As Long ' return value 





' Get a handle to the solid black pen and set it as Forml's drawing pen. 
hpen = GetStockObject (BLACK_PEN) ' get a handle to the pen 


holdpen = SelectObject (Forml.hDC, hpen) ' set it as Forml's current pen 























' The ellipse is determined by the bounding rectangle (0,50)-(200,150). 
' The radial to (200, 100) is due right; the radial to (0, 100) is due left. 
retval = Arce(Forml.hDC, 0, 50, 200, 150, 200, 100, 0, 100) 





' Restore Forml's previous pen selection. 
retval = SelectObject (Form1l.hDC, holdpen) " set the old pen back 























See Also 


AngleArc, ArcTo, Ellipse, GetArcDirection, SetArcDirection 


Category 


Lines & Curves 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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ArcTo Function 





Declare Function ArcTo Lib "gdi32.d1l" (ByVal hdc As Long, ByVal nLeftRect As Long, 
ByVal nTopRect As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long, ByVal 
nXRadiall As Long, ByVal nYRadiall As Long, ByVal nXRadial2 As Long, ByVal nYRadial2 
As Long) As Long 





























Platforms 


Windows 95: Not Supported 

Windows 98: Not Supported 

Windows NT: Requires Windows NT 3.1 or later 
Windows 2000: Supported 

Windows CE: Not Supported 


Description & Usage 





ArcTo draws an elliptical arc on a device using the device's current pen. After drawing the arc, the device's current point is set 
to the end point of the arc. The ellipse which the arc lies on is inscribed within the bounding rectangle coordinates passed to 
the function. The start and end points are determined by two radials. The radials begin at the center of the ellipse and extend 
through the given radial point (either the start or end one); where they intersect the ellipse is where the start and end points of 
the arc are. The direction the arc is drawn in depends on the device's current setting. 


Return Value 


If an error occured while attempting to draw the arc, the function returns 0 (call GetLastError to get the error code). If the 
function completed successfully, it returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 

A handle to a device context of the device to draw the arc on. 
nLeftRect 

The x coordinate of the upper-left point of the ellipse's bounding rectangle. 
nTopRect 

The y coordinate of the upper-left point of the ellipse's bounding rectangle. 
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nRightRect 

The x coordinate of the lower-right point of the ellipse's bounding rectangle. 
nBottomRect 

The y coordinate of the lower-right point of the ellipse's bounding rectangle. 
nXRadiall 

The x coordinate of the radial point that determines the arc's starting point. 
nYRadiall 

The y coordinate of the radial point that determines the arc's starting point. 
nXRadial2 

The x coordinate of the radial point that determines the arc's ending point. 
nYRadial2 

The y coordinate of the radial point that determines the arc's ending point. 


Example 


' This code is licensed according to the terms and conditions listed here. 























' Draw the arc that forms the top half of an ellipse. The ellipse 

' is centered at (100, 100), has a width of 200, and has a height of 100. The arc is 
drawn 

' on window Forml using the black solid stock pen. 











Dim hpen As Long ' handle to the black solid pen 
Dim holdpen As Long ' handle to window Forml's previously selected pen 
Dim retval As Long ' return value 





' Get a handle to the solid black pen and set it as Forml's drawing pen. 
hpen = GetStockObject (BLACK_PEN) ' get a handle to the pen 


holdpen = SelectObject (Forml.hDC, hpen) ' set it as Forml's current pen 























' The ellipse is determined by the bounding rectangle (0,50)-(200,150). 
' The radial to (200, 100) is due right; the radial to (0, 100) is due left. 
retval = ArcTo(Forml.hDC, 0, 50, 200, 150, 200, 100, 0, 100) 








' Restore Forml's previous pen selection. 
retval = SelectObject (Form1l.hDC, holdpen) ' set the old pen back 

















See Also 


AngleArc, Arc, Ellipse, GetArcDirection, SetArcDirection 


Category 


Lines & Curves 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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auxGetDevCaps Function 


Declare Function auxGetDevCaps Lib "winmm.dll" Alias "auxGetDevCapsA" 
(ByVal uDeviceID As Long, lpCaps As AUXCAPS, ByVal cbCaps As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


auxGetDevCaps retrieves information about the capabilities of an auxiliary audio device. This function can 
also retrieve capabilities information about the auxiliary audio mapper, if one exists. 





Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


uDeviceID 
The device ID of the auxiliary audio device. Valid IDs range from 0 to the total number of auxiliary 
audio devices minus one. This could also be the following flag: 
AUX_MAPPER 
Retrieve information about the capabilities of the auxiliary audio mapper. 
lpCaps 


http://216.26.168.92/vbapi/ref/a/auxgetdevcaps.html (1 of 3) [9/1/2002 5:03:35 PM] 


Windows API Guide: auxGetDevCaps Function 


Receives information about the device's capabilities. 
cbCaps 
The size in bytes of the structure passed as /pCaps. 


Constant Definitions 


Const AUX_MAPPER = -1 


Example 


1 


1 


Loop through each auxiliary audio device installed on the system 


' and display its name and version number. 











Dim auxinfo As AUXCAPS ' receives info about each device 

Dim numdevs As Long ' number of auxiliary audio devices installed 

Dim devname As String ' name of device 

Dim majver As Integer, minver As Integer ' major and minor version numbers 
Dim c As Long ' counter variable 

Dim retval As Long ' return value 

' Find out how many auxiliary audio devices are installed. 

numdevs = auxGetNumDevs () 








1 


Loop through each one, displaying its name and version number. 





For c = 0 To numdevs - 1 ' remember that device IDs are zero-based! 
' Get the capabilities of this device. 
retval = auxGetDevCaps(c, auxinfo, Len(auxinfo) ) 


If retval = 0 Then 
Debug.Print "** AUXILIARY AUDIO DEVICE"; c; "**" 
' Extract and display the name of the device. 





devname = Left (auxinfo.szPname, InStr(auxinfo.szPname, vbNullChar) 
Debug.Print "Name: "; devname 
' Extract and display the version number of the device. 
majver = (auxinfo.vDriverVersion And &HFF00) / &H100 ' major version 
minver = auxinfo.vDriverVersion And &HFF ' minor version 
Debug.Print "Version Number:"; majver; "."; minver 

Else 





Debug.Print "Could not get information about device"; c; "." 
End If 


Next c 





Category 
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Audio 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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auxGetNumDevs Function 


Declare Function auxGetNumDevs Lib "winmm.dll" () As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


auxGetNumDevs determines how many auxiliary audio devices are installed on the computer. This could be 


less than the number of devices actually present on the computer, since it is possible for a device to be installed 
yet not be connected or functioning. 


Return Value 
The function returns the number of auxiliary audio devices installed on the system. 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


1 


This code is licensed according to the terms and conditions listed here. 
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' Loop through each auxiliary audio device installed on the system 

' and display its name and version number. 

Dim auxinfo As AUXCAPS ' receives info about each device 

Dim numdevs As Long ' number of auxiliary audio devices installed 

Dim devname As String ' name of device 

Dim majver As Integer, minver As Integer ' major and minor version numbers 
Dim c As Long ' counter variable 

Dim retval As Long ' return value 

' Find out how many auxiliary audio devices are installed. 

numdevs = auxGetNumDevs () 





' Loop through each one, displaying its name and version number. 





For c = 0 To numdevs - 1 ' remember that device IDs are zero-based! 
" Get the capabilities of this device. 
retval = auxGetDevCaps(c, auxinfo, Len(auxinfo) ) 





If retval = 0 Then 
Debug.Print "** AUXILIARY AUDIO DEVICE"; c; "**" 
' Extract and display the name of the device. 
devname = Left (auxinfo.szPname, InStr(auxinfo.szPname, vbNullChar) - 1) 
Debug.Print "Name: "; devname 
' Extract and display the version number of the device. 
majver = (auxinfo.vDriverVersion And &HFF00) / &H100 ' major version 
minver = auxinfo.vDriverVersion And &HFF ' minor version 
Debug.Print "Version Number:"; majver; "."; minver 
Else 
Debug.Print "Could not get information about device"; c; "." 
End If 
Next c 





Category 
Audio 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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auxGetVolume Function 








Declare Function auxGetVolume Lib "winmm.dll" (ByVal uDeviceID As Long, 
lpdwVolume As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


auxGetVolume retrieves the current volume setting for an auxiliary audio device. This function will retreive 





the volume whether the device supports dual-channel volume control or not. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


uDevicelD 
The device ID of the auxiliary audio device to retrieve the volume of. Valid values range from 0 to the 
number of auxiliary audio devices minus one. 

lpdwVolume 
Receives the volume settings of the device. If the device supports separate left and right channel 
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volumes, the low-order word contains the left channel volume and the high-order word contains the 


right channel volume. If the device does not support separate volumes, the low-order word contains the 
overall volume. Valid volume settings range from &HO or & HFFFF. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Display the current volume setting of whatever device happens 














" to be auxiliary audio device 0. This example identifies whether the 

' device has dual-channel volumes or not. 

Dim auxinfo As AUXCAPS ' receives information about the device 

Dim numvols As Long ' identifies number of volumes on the device 

Dim lrvol As Long ' volumes of both channels (or just the overall volume) 
Dim lvol As Integer, rvol As Integer ' volumes of left and right channels 
Dim retval As Long ' return value 





' Figure out whether the device has one or two volume settings. 






































retval = auxGetDevCaps(0, auxinfo, Len(auxinfo) ) 

If retval <> 0 Then ' error 
Debug.Print "Could not access auxiliary audio device 0 -- aborting.” 
End ' give up 

End If 

If (auxinfo.dwSupport And AUXCAPS_LRVOLUME) = AUXCAPS_LRVOLUME Then 
numvols = 2 ' separate left and right volumes 

Else 
numvols = 1 ' only one overall volume 

End If 

' Determine the device's current volume. 

retval = auxGetVolume(0, lrvol) 

" Display the current volume setting for the device. 

If numvols = 2 Then 
' Separate the left and right channel volumes. The next two lines look 





' like an excessively complicated way of doing it, but because of a 
' quirk in Visual Basic, the "obvious" way doesn't work properly. 
lvol = Val("&H" & Hex(lrvol And (Not &HFFFFOOOO) ) ) 
rvol = (lrvol And &HFFFFO000) / &H10000 
' Display the results in hexadecimal. 
Debug.Print "Left Channel volume: "; Hex(lvol) 
Debug.Print "Right Channel volume: "; Hex(rvol) 
Else 
' Extract the useful information as above, although we only want 
' the low-order word (placed into lvol). 
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lvol = Val("&H" & Hex(lrvol And (Not &HFFFFOOOO) )) 

' Display the results in hexadecimal. 

Debug.Print “Volume: "; hex (lvol) ' here, lvol is the overall volume 
End If 





See Also 


auxSet Volume 


Category 
Audio 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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auxSetVolume Function 








Declare Function auxSetVolume Lib "winmm.dll" (ByVal uDeviceID As Long, 
ByVal dwVolume As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


auxSetVolume sets the current volume of an auxiliary audio device. This function works whether the device 





supports separate left and right channel volumes or not. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


uDevicelD 
The device ID of the auxiliary audio device to set the volume of. Valid values range from zero to the 
number of auxiliary audio devices minus one. 

dwVolume 
The new volume setting of the device. If the device supports separate left and right channel volumes, 
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the low-order word contains the left channel volume and the high-order word contains the right channel 


volume. If the device supports only one overall volume, the low-order word is the volume. Valid 
volumes range from &H0O to & HFFFF. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Set the volume of auxiliary audio device 0 to 50%. Here, 

' we don't care whether the device supports separate volumes or 
" not, since the code works either way. 

Dim retval As Long ' return value 





' Set the volume of both channels (if a second exists) to 50% (&H8000). 
retval = auxSetVolume(0, &H80008000) " both words are set 





See Also 


auxGetVolume 


Category 
Audio 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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Beep Function 


Declare Function Beep Lib "kernel32.dll1" (ByVal dwFreq As Long, ByVal 
dwDuration As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Beep plays a sound, but its exact behavior varies between platforms. Windows 95/98: The function always plays the 
SystemDefault system sound, regardless of the values passed to the function. Windows NT/2000: The function plays 
a tone through the computer's internal speaker at the desired frequency for a specified duration. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None 


Parameters 


dwF req 

Windows NT/2000: The frequency, in hertz (Hz), of the tone to play. Windows 95/98: Ignored. 
dwDuration 

Windows NT/2000: The duration, in milliseconds, to play the desired tone. Windows 95/98: Ignored. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Attempt to play a note at 800 Hz for 2 seconds. This will only 
' behave this way on Windows NT/2000; users of Windows 95/98 will only hear the 


' default sound. 
Dim retval As Long ' return value 


retval = Beep(800, 2000) ' ideally, an 800 Hz tone for 2 seconds 


See Also 


MessageBeep 


Category 


Errors 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


Last Modified: July 26, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/b/beep.html 
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BitBit Function 


Declare Function BitBlt Lib "gdi32.d1l1" (ByVal hdcDest As Long, ByVal nXDest 
As Long, ByVal nYDest As Long, ByVal nWidth As Long, ByVal nHeight As Long, 
ByVal hdcSrce As Long, ByVal nXSrc As Long, ByVal nYSrc As Long, ByVal dwRop 
As Long) As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


BitBlt performs a bit-block transfer of a rectangular portion of an image from one device to another. The 
dimensions of the transfered rectangle are perfectly preserved. The function can perform a variety of raster 
operations to transfer the block from the source device to the target device. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdcDest 
A handle to the device context of the device which receives the transfered image block. 
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nXDest 
The x-coordinate of the point to position the upper-left corner of the transfered image block. 
nYDest 
The y-coordinate of the point to position the upper-left corner of the transfered image block. 
nWidth 
The width in pixels of the image block. 
nHeight 
The height in pixels of the image block. 
hdcSrc 
A handle to the device context of the device which contains the image block to transfer. 
nXSrc 
The x-coordinate of the upper-left corner of the image block to transfer. 
nYSrc 
The y-coordinate of the upper-left corner of the image block to transfer. 
dwRop 
One of the following flags identifying the raster operation to use to transfer the image block. Each raster 
operation uses the RGB color value of the source and/or target pixel to determine the new color of the 
target pixel. 
BLACKNESS 
Fill the destination rectangle with the color whose index is 0 in the physical palette (which is black 
by default). 
CAPTUREBLT 
Windows 98, 2000: Include any windows layered on top of the window being used in the resulting 
image. 
DSTINVERT 
Invert the colors in the destination rectangle. 
MERGECOPY 
Merge the colors of the source rectangle with the specified pattern using the bitwise AND operator. 
MERGEPAINT 
Merge the colors of the inverted source rectangle with the colors of the destination rectangle using 
the bitwise OR operator. 
NOMIRRORBITMAP 
Windows 98, 2000: Prevent the bitmap from being mirrored. 
NOTSRCCOPY 
Copy the inverted source rectangle to the destination rectangle. 
NOTSRCERASE 
Combine the colors of the source and destination rectangles using the bitwise OR operator and then 
invert the resulting color. 
PATCOPY 
Copy the specified pattern into the destination bitmap. 
PATINVERT 
Combine the colors of the specified pattern with the colors of the destination rectangle using the 
bitwise XOR operator. 
PATPAINT 
Combine the colors of the specified pattern with the colors of the inverted source rectangle using 
the bitwise OR operator. Combine the result of that operation with the colors of the destination 
rectangle using the bitwise OR operator. 
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SRCAND 
Combine the colors of the source and destination rectangles using the bitwise AND operator. 
SRCCOPY 
Copy the source rectangle directly into the destination rectangle. 
SRCERASE 
Combine the inverted colors of the destination rectangle with the colors of the source rectange 
using the bitwise AND operator. 
SRCINVERT 
Combine the colors of the source and destination rectangles using the bitwise XOR operator. 
SRCPAINT 
Combine the colors of the source and destination rectangles using the bitwise OR operator. 
WHITENESS 
Fill the destination rectangle with the color whose index is 1 in the physical palette (which is white 
by default). 


Constant Definitions 




















Const BLACKNESS = &H42 

" Const CAPTUREBLT = ??? 
Const DSTINVERT = &H550009 
Const MERGECOPY = &HCOOOCA 
Const MERGEPAINT = &HBBO226 
" Const NOMIRRORBITMAP = ??? 
Const NOTSRCCOPY = &H330008 
Const NOTSRCERASE = &H1100A6 
Const PATCOPY = &HF00021 
Const PATINVERT = &H5A0049 
Const PATPAINT = &HFBOAO9 
Const SRCAND = &H8800C6 
Const SRCCOPY = &HCC0020 
Const SRCERASE = &H440328 
Const SRCINVERT = &H660046 
Const SRCPAINT = &HEEO086 
Const WHITENESS = &HFFO062 
Example 


' 


' 


Dim retval As Long ' 


This code is licensed according to the terms and conditions listed here. 


Copy a rectanglular image from window Forml to window Form2 
exactly (using SRCCOPY). 
50. The upper-left corner of the source block is 
is placed at (0,0) in Form2. 

return value 


(350, 250); the block 
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The rectangle has a width of 100 and a height of 
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' Transfer the image exactly as described above. 
retval = BitBlt(Form2.hDC, 0, 0, 100, 50, Forml.hDC, 


See Also 
StretchBlt 
Category 
Bitmaps 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 13, 1999 


350; 


250, 


SRCCOPY) 


This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/b/bitblt.html 
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BringWindowToTop Function 


Declare Function BringWindowToTop Lib "user32.dll1" (ByVal hwnd As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


BringWindowToTop brings a specified window to the top of the Z-order, placing it above any windows previously 
on top of it. This function has the same effect as using SetWindowPos to place the window at the top of the Z-order. 








Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None 


Parameters 


hwnd 
A handle to the window to bring to the top of the Z-order. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' Bring the window Forml to the top of the Z-order. 
Dim retval As Long ' return value 


' Obviously, this will only do something if other windows are already on top of 
Forml. 
retval = BringWindowToTop (Form1.hWnd) 


See Also 


SetWindowPos 


Category: 
Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: July 28, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/b/bringwindowtotop.html 
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CallWindowProc Function 








Declare Function CallWindowProc Lib "user32.d11" Alias "CallWindowProcA" (ByVal 
lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam As Long, 
ByVal lParam As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CallWindowProc explicitly calls the hook function acting as a window's procedure to process a message. This allows a 
message for a window to be processed by a window procedure which is not necessarily the one normally called by the 
window. 


Return Value 


The function returns the return value generated after processing the message sent. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpPrevWndFunc 
A pointer to the window procedure function to call explicitly. This is the function which will process the message. 
hWnd 
A handle to the window to process the message for. 
Msg 
The message to process. 
wParam 
Additional information about the message. 
lParam 
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Additional information about the message. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Have window Forml play the SystemAsterisk sound whenever it gets 

' or loses the focus. Do this by specifying a new window procedure which 
' plays the sound whenever the WM_ACTIVATE message is received. To 

" process all other messages (and do whatever else WM_ACTIVATE should 

' do), the procedure then calls the previous window procedure. 











' xxx Place this code in a module. *** 





Const WM_ACTIVATE = &H6 ' identifier of the message 
' The following variable is accessible to all code in this example. 
Public pOldProc As Long ' pointer to the previous window function 








' Define the new window procedure. 
Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 
Long, ByVal lParam As Long) As Long 
Dim retval As Long 
' If the message is WM_ACTIVATE (we don't care about the parameters), 
' play the SystemAsterisk sound. 
Tf uMsg = WM_ACTIVATE Then 
retval = PlaySound("SystemAsterisk", 0, SND_ALIAS Or SND_ASYNC) 

End If 

' No matter what happened, use the old window procedure to 

' finish processing the message. 

retval = CallWindowProc(pOldProc, hWnd, uMsg, wParam, lParam) 

' Have this function return whatever the function above returned. 









































WindowProc = retval 
End Function 


' xxx Place the following code wherever you wish. *** 


Dim retval As Long ' return value 











' Set the new window procedure for Forml, saving a pointer to the old one. 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 


' Now WindowProc processes Forml's messages, playing the sound 
' whenever Forml is activated or loses activated status. 








See Also 


DefWindowProc 


Category 


Window Procedures 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 23, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/c/callwindowproc.html 
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ChangeDisplaySettings Function 














Declare Function ChangeDisplaySettings Lib "user32.dl1" Alias 





"ChangeDisplaySettingsA" (lpDevMode As Any, ByVal dwFlags As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ChangeDisplaySettings changes the current display settings. This function can change the current screen resolution and 
color depth, among other things. Typically, a call to EnumDisplaySettings should preceed this function, in order to adjust 


only the desired settings. 


Return Value 


The function returns one of the following flags: 


DISP_CHANGE_SUCCESSFUL 
The display settings were successfully changed. 
DISP_CHANGE_RESTART 


The computer must be restarted for the display changes to take effect. 


DISP_CHANGE_BADFLAGS 

An invalid set of flags was specified. 
DISP_CHANGE_BADPARAM 

An invalid parameter was specified. 
DISP_CHANGE_FAILED 

The display driver failed the specified graphics mode. 
DISP_CHANGE_BADMODE 

The specified graphics mode is not supported. 
DISP_CHANGE_NOTUPDATED 

Windows NT/2000: The settings could not be written to the registry. 


Visual Basic-Specific Issues 
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When specifying zero for IpDevMode, use the expression ByVal CLng(0). 


Parameters 


lpDevMode 


A DEVMODE structure that holds the new display settings. Only the dmBitsPerPixel, dmPelsWidth, 


dmPelsHeight, dmDisplayFlags, and dmDisplayFrequency members are used. (Windows 98, NT/2000: The 
dmPosition member can also be used.) To restore the settings saved in the registry, set this parameter and dwFlags 
to zero. 


dwFlags 


A combination of the following flags specifying how to change the display mode. If no flags are set (1.e., zero is 
specified), the graphics mode is changed dynamically. 
CDS_UPDATEREGISTRY 
Save the new settings to the registry and also change the settings dynamically. 
CDS_TEST 
Test to see if the new settings are supported by the hardware, without actually changing the settings. The 
function's return value will indicate any problems that may have occured. 
CDS_FULLSCREEN 
Go into full-screen mode. This setting cannot be saved. 
CDS_GLOBAL 
Save the new settings for all users. The CDS_UPDATEREGISTRY flag must also be specified. 
CDS_SET_PRIMARY 
Make this device the primary display device. 
CDS_RESET 
Change the settings even if they are the same as the current settings. 
CDS_NORESET 
Save the settings to the registry, but do not make them take effect yet. The CDS_UPDATEREGISTRY flag 
must also be specified. 


Constant Definitions 


Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 





Con 




































































st CDS_UPDATEREGISTRY = &H1 
st CDS_TEST = &H2 

st CDS_FULLSCREEN = &H4 

st CDS_GLOBAL = &H8 

st CDS_SET_PRIMARY = &H10 

st CDS_RESET = &H40000000 

st CDS_SETRECT = &H20000000 
st CDS_NORESET = &H10000000 
st DISP_CHANGE_SUCCESSFUL = 0 
st DISP_CHANGE_RESTART = 1 

st DISP_CHANGE_ FAILED = -1 

st DISP_CHANGE_BADMODE = -2 
st DISP_CHANGE_NOTUPDATED = -3 
st DISP_CHANGE_BADFLAGS = -4 
st DISP_CHANGE_BADPARAM = -5 
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Example 


Change the current screen resolution to 800x600 without changing the color depth and save the changes to the registry. 
First test to make sure that the hardware supports the new resolution. If a reboot is necessary, inform the user. To use this 
example, place a command button named Command 1 of a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type DEVMODE 
dmDeviceName As String * 32 
dmSpecVersion As Integer 
dmDriverVersion As Integer 
dmSize As Integer 
dmDriverExtra As Integer 
dmFields As Long 
dmOrientation As Integer 
dmPaperSize As Integer 
dmPaperLength As Integer 
dmPaperWidth As Integer 
dmScale As Integer 
dmCopies As Integer 
dmDefaultSource As Integer 
dmPrintQuality As Integer 
dmColor As Integer 
dmDuplex As Integer 
dmYResolution As Integer 
dmTTOption As Integer 
dmCollate As Integer 
dmFormName As String * 32 
dmUnusedPadding As Integer 
dmBitsPerPixel As Integer 
dmPelsWidth As Long 
dmPelsHeight As Long 
dmDisplayFlags As Long 
dmDisplayFrequency As Long 
' The following only appear in Windows 95, 98, 2000 
dmICMMethod As Long 
dmICMIntent As Long 
dmMediaType As Long 
dmDitherType As Long 
dmReservedl As Long 
dmReserved2 As Long 
' The following only appear in Windows 2000 
dmPanningWidth As Long 
dmPanningHeight As Long 
End Type 
Public Declare Function EnumDisplaySettings Lib "user32.d1ll" Alias 




















































































































http://216.26.168.92/vbapi/ref/c/changedisplaysettings.html (3 of 5) [9/1/2002 5:06:28 PM] 


Windows API Guide: ChangeDisplaySettings Function 





"EnumDisplaySettingsA" (ByVal lpszDeviceName As String, 
ByVal iModeNum As Long, lpDevMode As DEVMODE) As Long 























Public Const ENUM_CURRENT_SETTINGS = -1 
Public Declare Function ChangeDisplaySettings Lib "user32.d11" Alias 
"ChangeDisplaySettingsA" (lpDevMode As Any, ByVal dwFlags _ 








As Long) As Long 
Public Const CDS_UPDATEREGISTRY = &H1 
Public Const CDS_TEST = &H2 
Public Const DISP_CHANGE_ SUCCESSFUL = 0 
Public Const DISP_CHANGE_RESTART = 1 
































' *** Place the following code inside the form window. 





Private Sub Command1_Click () 
Dim dm As DEVMODE ' display settings 
Dim retval As Long ' return value 

















' Initialize the structure that will hold the settings. 
dm.dmSize = Len (dm) 

' Get the current display settings. 

retval = EnumDisplaySettings (vbNullString, ENUM_CURRENT_SETTINGS, dm) 
' Change the resolution settings to 800x600. 
dm.dmPelswWidth = 800 

dm.dmPelsHeight = 600 

' Test to make sure the changes are possible. 

retval = ChangeDisplaySettings (dm, CDS_TEST) 

Tf retval <> DISP_CHANGE_SUCCESSFUL Then 

Debug.Print "Cannot change to that resolution!" 









































Else 





' Change and save to the new settings. 

retval = ChangeDisplaySettings (dm, CDS_UPDATEREGISTRY) 

Select Case retval 

Case DISP_CHANGE_ SUCCESSFUL 

Debug.Print "Resolution successfully changed!" 

Case DISP_CHANGE_ RESTART 

Debug.Print "A reboot is necessary before the changes will 
































take effect." 

Case Else 
Debug.Print "Unable to change resolution!" 
End Select 








End If 
End Sub 





See Also 


EnumDisplaySettings 





Category 
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Devices 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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CharLower Function 


Declare Function CharLower Lib "user32.d1ll1" Alias "CharLowerA" (ByVal lpsz 
As String) As String 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CharLower converts all of the upper-case letters in a string into lower-case. The function also sets the string 
passed to the function to the returned string; in reality they become the same thing. 


Return Value 


The function returns the string, with all upper-case letters converted to lower-case. 


Visual Basic-Specific Issues 


None. 


Parameters 


Ipsz 
The string to convert to lower-case. 


Example 
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' This code is licensed according to the terms and conditions listed here. 





" Convert the string "Hello, World!" into lower-case. 

Dim target As String ' target string 

target = CharLower("Hello, World!") " Convert to lower-case 
Debug.Print target ' Output should be "hello, world!" 

See Also 

CharUpper 


Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: July 30, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/c/charlower.html 
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CharUpper Function 


Declare Function CharUpper Lib "user32.d11" Alias "CharUpperA" (ByVal lpsz 
As String) As String 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CharUpper converts all of the lower-case letters in a string into upper-case. The function also sets the string 
passed to the function to the returned string; in reality they become the same thing. 


Return Value 


The function returns the string, with all lower-case letters converted to upper-case. 


Visual Basic-Specific Issues 


None. 


Parameters 


Ipsz 
The string to convert to upper-case. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Convert the string "Hello, World!" into upper-case. 





Dim target As String ' target string 

target = CharUpper("Hello, World!") * Convert to upper-case 
Debug.Print target ' Output should be "HELLO, WORLD!" 

See Also 

CharLower 


Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: July 30, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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ChooseColor Function 





Declare Function ChooseColor Lib "comdlg32.d11" Alias "ChooseColorA" (lpcc As 
CHOOSECOLOR TYPE) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


ChooseColor opens a Choose Color common dialog box. All the information needed to create the dialog box, as well as the 
data returned from it, is stored in the structure passed as Ipcc. 


Return Value 


If an error occured or the user pressed the Cancel button, the function returns 0 (use CommDI|gExtendedError to get the error 
code). If the user successfully selected a color, the function returns a non-zero value. 





Visual Basic-Specific Issues 


None. 


Parameters 


Ipce 
All the information needed to create the Choose Color common dialog box. If successful, the function then stores the 
user's color selection and list of custom colors into this structure as well. 


Example 


This code is licensed according to the terms and conditions listed here. 





Display a Choose Color common dialog box. The background 
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color 


of Form] 


will be set to the color the user selects. Although the entire 











list of custom col 
colors into an array which can be used again to save the user's custom 














Ors 





is initialized to black, this example stores the 
































color selections. 
Dim cc As CHOOSECOLOR TYPE ' structure to pass data 
Dim hMem As Long ' handle to the memory block to store the custom color list 
Dim pMem As Long ' pointer to the memory block to store the custom color list 
Dim custcols(0 To 15) As Long ' holds list of the 16 custom colors 
Dim c As Integer ' counter variable 
Dim retval As Long ' return value 
' Initialize the list of custom colors to black. 
For c = 0 To 15 ' loop through each element 
custcols(c) = 0 ' set each element to RGB color 0 (black) 
Next c 
' Create a memory block and get a pointer to it. 
hMem = GlobalAlloc (GMEM MOVEABLE Or GMEM_ZEROINIT, 64) ' allocate sufficient memory 
block 
pMem = GlobalLock (hMem) " get a pointer to the block 


ec. SCY 


cc.hwndOwner 


cc.hiIns 


cc.rgbResult 


color 
cc.lpCu 


cc.Flags 


selecti 
cc.1Cus 
cc.lpfn 


cc.lpTe 





retval 


If retval <> 0 
Copy the possibly altered contents of the custom color list 
back into the array. 

CopyMemory custcol 
Set Forml's background color. 
Forml.BackColor 


End If 





Deal 
retval 














E 
0 
FE 


uctSize 


tance 


stColors 
CC_AN 


on 
tData 
Hook 





0 
0 


mplateName 


Open the Choose Color box. 
background col 


ChooseC 


m 





locate the 


= GlobalU 


Copy the data inside the array into the memory block. 
CopyMemory ByVal pMem, 


custcols(0), 64 16 elements * 4 bytes 


Store the initial settings of the Choose Color box. 


Len (cc) size of the structure 

orml.hwnd Forml is opening the Choose Color box 
" not needed 

orml.BackColor 


set default selected color to Forml's background 








T a 


custom colors 
use rgbResult as default 


list o 
' allow any color, 





pMem pointer to 

YCOLOR Or CC_RGBINIT 
" not needed 
not needed 

wm not needed 


If the set Forml's 
or to that color. 
olor (cc) 


hen " success 


user chooses a color, 





s(0), ByVal pMem, 64 





cc.rgbResult 


memory blocks to free up resources. 
nlock (hMem) 








retval 











= GlobalF 


ree (pMem) 
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Common Dialog 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 14, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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ChooseFont Function 








Declare Function ChooseFont Lib "comdlg32.d11" Alias "ChooseFontA" (lpcf As 
CHOOSEFONT TYPE) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ChooseFont opens the Choose Font common dialog box. All of the necessary information needed to create the dialog box, 
as well as all of the information returned from it, is stored in the structure passed as pChooseFont. The logical font 
information is mostly stored in a LOGFONT structure, which can be used to access that font. 


Return Value 


If an error occured or the user pressed Cancel, the function returns 0 (use CommDIgExtendedError to get the error code). If 
the user successfully selected a font, the function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


Ipcf 
Passes information to and from the Choose Font dialog box. Initialize this before calling the function, and read the 
necessary information from it afterwards. 


Example 


This code is licensed according to the terms and conditions listed here. 
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' Display a Choose Font dialog box. Print out the typeface name, point size, 

' and style of the selected font. More detail about topics in this example can be 
found in 

" the pages for CHOOSEFONT TYPE and LOGFONT. 





































































































Dim cf As CHOOSEFONT TYPE ' data structure needed for function 

Dim lfont As LOGFONT ' receives information about the chosen font 

Dim hMem As Long, pMem As Long ' handle and pointer to memory buffer 

Dim fontname As String ' receives name of font selected 

Dim retval As Long ' return value 

' Initialize the default selected font: Times New Roman, regular, black, 12 point. 
' (Note that some of that information is in the CHOOSEFONT_TYPE structure instead.) 
lfont.1lfHeight = 0 ' determine default height 

lfont.1lfWidth = 0 ' determine default width 

lfont.1fEscapement = 0 ' angle between baseline and escapement vector 
lfont.1fOrientation = 0 ' angle between baseline and orientation vector 
lfont.1lfWeight = FW_NORMAL ' normal weight i.e. not bold 

lfont.1lfItalic = 0 ' not italic 

lfont.1fUnderline = 0 ' not underline 

lfont.1fStrikeOut = 0 ' not strikeout 

lfont.1lfCharSet = DEFAULT_CHARSET " use default character set 
lfont.1fOutPrecision = OUT_DEFAULT_PRECIS ' default precision mapping 
lfont.1lfClipPrecision = CLIP_DEFAULT_PRECIS ' default clipping precision 
lfont.1lfQuality = DEFAULT_QUALITY ' default quality setting 
lfont.1fPitchAndFamily = DEFAULT_PITCH Or FF_ROMAN ' default pitch, proportional 
with serifs 

lfont.1fFaceName = "Times New Roman" & vbNullChar ' string must be null-terminated 











' Create the memory block which will act as the LOGFONT structure buffer. 
hMem = GlobalAlloc(GMEM_ MOVEABLE Or GMEM_ZEROINIT, Len(lfont) ) 








= 





























pMem = GlobalbLock (hMem) ' lock and get pointer 
CopyMemory ByVal pMem, lfont, Len(lfont) " copy structure's contents into block 


' Initialize dialog box: Screen and printer fonts, point size between 10 and 72. 




















cf.1lStructSize = Len(cf) ' size of structure 

cf.hwndOwner = Forml.hWnd ' window Forml is opening this dialog box 

cf.hdc = Printer.hDC ' device context of default printer (using VB's mechanism) 
cf.lfLogFont = pMem ' pointer to LOGFONT memory block buffer 

cf.iPointSize = 120 ' 12 point font (in units of 1/10 point) 

cf.flags = CF_BOTH Or CF_EFFECTS Or CF_FORCEFONTEXIST Or CF_INITTOLOGFONTSTRUCT Or 





























CF_LIMITSIZE 

















cf.rgbColors = RGB(0, 0, 0) ' black 

cf.lCustData = 0 ' we don't use this here... 

cf.lpfnHook = 0 ' ...or this... 

cf.lpTemplateName = ""  ' ...0or this... 

cf.hInstance = 0 ' ...or this... 

cf.lpszStyle = "™" T1 ...or this 

cf.nFontType = REGULAR_FONTTYPE ' regular font type i.e. not bold or anything 
cf.nSizeMin = 10 ' minimum point size 

cf.nSizeMax = 72 ' maximum point size 
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' Now, call the function. 
structure 
' and then print out the 


If successful, 











copy the LOGFONT structure back into the 


attributes we mentioned earlier that the user selected. 





retval = ChooseFont (cf) ' open the dialog box 
If retval <> 0 Then " success 
CopyMemory lfont, ByVal pMem, Len (lfont) ' 





' Now make the fixed-length string 
fontname Left (1font.lfFaceName, 

' Display font name and a few attributes. 
Debug.Print "FONT NAME: "; fontname 
Debug.Print "FONT SIZE (points): "; 
Debug.Print "FONT STYLE(S): "; 

If lfont.lfWeight >= FW_BOLD Then 
If lfont.1lfItalic <> 0 Then Debug. 


holding 


























W 





Print 














InStr(lfont.1fFaceName, 


cf.iPointSize / 10 ' 


Debug.Print 
Italic "i 


copy memory back 


the font name into a "normal" 
vbNullChar) 


string. 


1) 





in units of 1/10 point! 


"Böl 


" 


d Wes 





If lfont.1fUnderline <> 0 Then Deb 
If lfont.1fStrikeOut <> 0 Then Deb 
Debug.Print ' end the line 

End If 





ug.Print 
ug.Print 





























' Deallocate the memory block w 


created earlier. 





"Underline "; 
"Strikeout"; 


Note that this must 








' p 
retval 


obalUnlock (hMem) 1 


Free (hMem) ’ 











Gl 
Gl 








retval obal 





Category 


Common Dialog 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 19, 1999 


done whether the function succeeded or not. 
destroy pointer, 


unlock block 


free the allocated memory 


This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





Go back to the Windows API Guide home page. 
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Chord Function 


Declare Function Chord Lib "gdi32.dll1" (ByVal hdc As Long, ByVal nLeftRect As 
Long, ByVal nTopRect As Long, ByVal nRightRect As Long, ByVal nBottomRect As 
Long, ByVal nXRadiall As Long, ByVal nYRadiall As Long, ByVal nXRadial2 As Long, 
ByVal nYRadial2 As Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Chord draws an elliptical chord on a device. The chord is drawn using the device's currently selected pen and is filled 





using its currently selected brush. The chord consists of a line segment connecting two points along an ellipse; the area 
between the chord and the ellipse's edge is filled (going counterclockwise around the ellipse). The start and end points of 
the chord's elliptical arc are determined by two radials (drawn from the ellipse's center out to a point). The point where a 
radial and the ellipse intersect is the start or end point of the chord's arc. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 
None. 


Parameters 


hdc 
A handle to a device context to the device to draw the chord on. 


nLeftRect 
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The x-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
nTopRect 

The y-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
nRightRect 

The x-coordinate of the lower-right corner of the ellipse's bounding rectangle. 
nBottomRect 

The y-coordinate of the lower-right corner of the ellipse's bounding rectangle. 
nXRadiall 

The x-coordinate of the point along the radial determining the starting point of the chord. 
nYRadiall 

The y-coordinate of the point along the radial determining the starting point of the chord. 
nXRadial2 

The x-coordinate of the point along the radial determining the ending point of the chord. 
nYRadial2 

The y-coordinate of the point along the radial determining the ending point of the chord. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Draw a chord on window Forml. The ellipse has a bounding rectangle 

' of (10,20)-(210,120). The chord will have endpoints on the ellipse of (210,70) 
' and (110,20) -- i.e., the "upper-right" portion of the ellipse. Draw the chord 
using 

' Forml's current brush and pen. 

Dim retval As Long ' return value 


' Draw the chord as specified above. 
retval = Chord(Forml.hDC, 10, 20, 210, 120, 210, 70, 110, 20) 





See Also 
Ellipse, Pie 
Category 


Filled Shapes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: September 10, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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ClipCursor Function 


Declare Function ClipCursor Lib "user32.dl1" (lpRect As RECT) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ClipCursor confines the mouse cursor to a rectangular area of the screen. If the user tries to move the cursor 
outside of this bounding region or a call to SetCursorPos tells it to go outside the box, the cursor will 


immediately returned to the area. There is no way to get it out. This bounding effect will last in whatever 
program you switch to, and will remain even if the program that confined the cursor closes! The only way to 
"release" the cursor is to "confine" it to the entire screen (see example). It isn't usually a good idea to confine 
the cursor, since the user expects to move the cursor anywhere (not to mention the disasterous effect if your 
program quit before releasing the cursor!). 


Return Value 


If an error occured, the function returns zero (call GetLastError to get the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 
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IpRect 
The rectangle (in screen coordinates) defining the confinement rectangle. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Confine the cursor temporarily to inside of Forml 





' ** Place the following code where you want to confine the cursor. ** 











Dim r As RECT ' confinement rectangle 

Dim retval As Long ' return value 

retval = GetWindowRect (Forml.hWnd, r) ' put window's coordinates into r 
retval = ClipCursor (r) ' confine the cursor 


' ** Place the following code where you want to release the cursor. ** 
Dim r As RECT, retval As Long 
Dim deskhWnd As Long ' the handle of the desktop window 














deskhWnd = GetDesktopWindow () " get handle of the desktop window 
retval = GetWindowRect (deskhWnd, r) ' put window's coordinates into r 








retval = ClipCursor (r) " "confine" the cursor to the entire screen 


See Also 
GetClipCursor 


Category 


Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last-Modified: September 10, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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CloseHandle Function 
Declare Function CloseHandle Lib "kernel32.dll1" (ByVal hObject As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CloseHandle closes a handle and the object associated with that handle. After being closed, the handle is of course no longer 





valid. This function closes handles associated with access tokens, communications devices, console inputs, console screen 
buffers, events, files, file mappings, jobs, mailslots, mutexes, named pipes, processes, semaphores, sockets, and threads. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non-zero 
value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hObject 
A handle to the object to close. 


Example 


' This code is licensed according to the terms and conditions listed here. 











' Display the date on which the file C:\MyApp\test.txt was 
' created. Note how the time zone conversion is necessary. 
Dim hFile As Long ' handle to the opened file 
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Dim ctime As FILETIME ' receives time of creation 

Dim atime As FILETIME ' receives time of last access 

Dim mtime As FILETIME ' receives time of last modification 
Dim thetime As SYSTEMTIME ' used to manipulate the time 
Dim retval As Long ' return value 














' First, open the file C:\MyApp\test.txt for read-level access. Note the 
' expression necessary to pass 0 as lpSecurityAttributes. 
hFile = CreateFile("C:\MyApp\test.txt", GENERIC_READ, FILE_SHARE READ, ByVal CLng(0), 


































































































OPEN_EXISTING, FILE _ATTRIBUTE_ARCHIVE, 0) 

If hFile = -1 Then 
Debug.Print "Could not open the file successfully -- aborting." 
End ' terminate the program 

End If 











' Next, get the creation, last-access, and last-modification times. 
retval = GetFileTime(hFile, ctime, atime, mtime) 














" Convert the creation time to the local time zone. 
retval = FileTimeToLocalFileTime(ctime, ctime) 

" Convert the FILETIME format to the SYSTEMTIME format. 
retval = FileTimeToSystemTime (ctime, thetime) 















































' Display the date of creation of the file to the user. 
Debug.Print "The file was created on "; thetime.wMonth; "-"; thetime.wDay; "-"; 
thetime.wYear 

















' Close the file to free up resources. 
retval = CloseHandle (hFile) 


Category 
Handles 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


Last Modified: October 1, 1999 
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ClosePrinter Function 
Declare Function ClosePrinter Lib "winspool.drv" (ByVal hPrinter As Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ClosePrinter closes a printer which had been previously opened by OpenPrinter. After this function closes the printer, the 
handle to the printer obviously can no longer be used, even if the function fails. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get the 
error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hPrinter 
A handle to the open printer to close. 


Example 


Display the Properties dialog box for the system's default printer. The dialog box is opened when the user clicks the button 
cmdProperties. To use the example, first place a command button named cmdProperties on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
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' (Copy them to the (declarations) section of a module.) 
Public Type PRINTER INFO 1 
flags As Long 
pDescription As String 
pName As String 
pComment As String 
End Type 
Public Declare Function EnumPrinters Lib "winspool.drv" Alias "EnumPrintersA" (ByVal 









































flags As Long, _ 
ByVal name As String, ByVal Level As Long, pPrinterEnum As Long, ByVal cdBuf 























As Long, _ 
pcbNeeded As Long, pcReturned As Long) As Long 
Public Const PRINTER_ENUM_DEFAULT = &H1 


Public Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 
































As Any, 


ByVal lpString2 As Any) As Long 





















































Public Declare Function lstrlen Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function OpenPrinter Lib "winspool.drv" Alias "OpenPrinterA" (ByVal 
pPrinterName _ 

As String, phPrinter As Long, pDefault As Any) As Long 
Public Declare Function PrinterProperties Lib "winspool.drv" (ByVal hWnd As Long, 


ByVal hPrinter _ 

As Long) As Long 
Public Declare Function ClosePrinter Lib "winspool.drv" (ByVal hPrinter As Long) As 
Long 




















' ***x Place the following code inside a form window. *** 


Private Sub cmdProperties_Click () 















































Dim pil As PRINTER INFO 1 ' a little info about the printer 

Dim bytesNeeded As Long ' size needed for buffer 

Dim numPrinters As Long ' number of printers enumerated (should be 1) 
Dim buffer() As Long ' buffer for printer information 

Dim slength As Long ' length of string to copy 

Dim hPrinter As Long ' handle to the printer 

Dim retval As Long ' generic return value 








' Figure out how much space is needed to store the printer information. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, vbNullString, 1, ByVal 0, 0, 
bytesNeeded, numPrinters) 

' Allocate that much space in the buffer array. 

ReDim buffer(0 To bytesNeeded / 4 =- 1) As Long 

' Get information about the default printer. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, vbNullString, 1, buffer(0), 
bytesNeeded, 































































































bytesNeeded, numPrinters) 
' Make sure we were successful. 
If retval = 0 Or numPrinters <> 1 Then 
Debug.Print "No default printer or some other error." 
Exit Sub 














End If 
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' Copy the data into the structure. 
































With pil 
' Copy numerical data directly. 
.flags = buffer (0) 
' Strings require more work, since the buffer holds pointers to them. 
-pDescription = Space (lstrlen (buffer (1))) 
retval = lstrcpy(.pDescription, buffer (1)) 
-pName = Space (lstrlen (buffer (2))) 
retval = lstre (.pName, buffer (2)) 
.pComment = Space (lstrlen (buffer (3))) 














) 
retval = lstrcpy(.pComment, buffer (3)) 
End With 





' Open the printer. 
retval = OpenPrinter(pil.pName, hPrinter, ByVal CLng(0)) 
If retval <> 0 Then 

' Display the properties dialog. 





























retval = PrinterProperties (Me.hWnd, hPrinter) 
" Close the printer. 
retval = ClosePrinter (hPrinter) 
Else 
Debug.Print "Unable to open printer!" 
End If 











End Sub 





See Also 
OpenPrinter 
Category 
Printers 


Go back to the Function listing. 
Go back to the Reference section index. 
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closesocket Function 





Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


closesocket closes a socket that had previously been created by a call to socket. Your program should call this function when it 
is finished using a socket, in order to free unneeded socket descriptors. 





Return Value 


If successful, the function returns zero. If an error occured, the function returns INVALID_SOCKET (use WSAGetLastError 
to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


A descriptor of the socket to close. 


Constant Definitions 


Const INVALID_SOCKET = &HFFFFFFFF 








Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 





http://216.26.168.92/vbapi/ref/c/closesocket.html (1 of 5) [9/1/2002 5:08:45 PM] 


Windows API Guide: closesocket Function 


HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 


Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 


called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 
had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 


' (Copy them to the 


Public 





End Typ 
Public 
Integer 





ublic 
ublic 
ublic 
ublic 
ong 
ublic 








Ue g tt tg. ty 





End Typ 
Public 
Integer 
Public 
As Long 


Public 


End Typ 
Public 
ByVal n 








Type WSADATA 


g£ 





(declarations) section of a module.) 


wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 











iMaxUdpDg As Long 





lpVendorInfo As Long 


= 





, lpWSAData _ 








Declare Function WSAStartup Lib "wsock32.dll1" (ByVal wVersionRequested As 





As WSADATA) As Long 











Const AF_INET = 2 
Const SOCK_STREAM = 














Declare Function WSACleanup Lib "wsock32.d11" () As Long 


1 





Declare Function gethostbyname Lib "wsock32.dll1" (ByVal name As String) As 











Type hostent 


h_name As Long 
h_aliases As Long 


h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 





(= 








r — 





Type sockaddr 











Declare Function htons Lib "wsock32.dll" (ByVal hostshort As Integer) As 











Declare Function socket Lib "wsock32.dll" (ByVal af As Long, ByVal prototype 


ByVal protocol As Long) As Long 


sin_family As Integer 
sin_port As Integer 


sin_addr As Long 
sin_zero As String 
e 





amelen _ 
As Long) As Long 


= 8 





Declare Function connect Lib "wsock32.dll" (ByVal s As Long, name As sockaddr, 
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Declare Function ioctlsocket Lib "wsock32.dl11" (ByVal s As Long, ByVal cmd As Long, 
argp As Long) As Long 
Public Const FIONBIO = &H8004667E 
Public Declare Function send Lib "wsock32.dl11" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function recv Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, 
ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.dll1" (ByVal s As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
Public Const SOCKET_ERROR = -1 
' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 
End Function 
' *** Place the following code inside the form window. *** 
Private Sub cmdDownload_Click () 
Dim wsockinfo As WSADATA ' info about Winsock 
Dim sock As Long ' the socket descriptor 
Dim pHostinfo As Long ' pointer to info about the host computer 
Dim hostinfo As hostent ' info about the host computer 
Dim plIPAddress As Long ' pointer to host's IP address 
Dim ipAddress As Long " host's IP address 
Dim sockinfo As sockaddr ' settings for the socket 
Dim buffer As String ' buffer for sending and receiving data 
Dim reply As String ' accumulates server's reply 
Dim retval As Long ' generic return value 

















' Begin a Winsock session. 


retval WSAStartup (MAK 





E WORD 








(2, 2), ws 





If retval <> 0 Then 








End 











' Get 
pHostinfo 
If p 


End 





" Copy int 
CopyMemory 
If hostinfo.h_addrt 
Debug.Print 





Debug.Print 
Exit Sub 


gethos 





EO 0O Then 





Hostinit 





If 


Debug.Prin 
GoTo Clean 





up 











forma 











hostinfo, 





ByVal 








P 


type <> AF_ 
"Couldn't 


£ 


ockinfo 


) 








"Unable to initialize Winsock! 














Hostinfo, 
INET Then 
get IP a 


retval 


We 
r 


information about the server to connect to. 
tbyname ("www.vbapi.com") 


"Unable to resolve host!" 





tion about the server into the structure. 





Len (hostinfo) 





ddress of www.vbapi.com!" 
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GoTo Cleanup 
End If 
' Get th 
CopyMemory plIPAddress, 
CopyMemory ipAddress, 











Create a socket. 
sock socket (AF_IN 











SOCK_STREAM, 











ET, 
If sock SOCKET_ERROR 
Debug.Print 
GoTo Cleanup 


R 














End If 





With sockinfo 





























Then 





0) 


Make a connection to www.vbapi.com:80 


server's IP address out of the structure. 
ByVal hostinfo.h_addr_list, 
ByVal pIPAddress, 


4 


4 


"Unable to create socket!" 


(where the web server 





listens). 


' Use Internet Protocol (IP) 

.-Sin_family = AF_INET 

" Connect to port 80. 

-Sin_port = htons (80) 

' Connect to this IP address. 

.Sin_addr = ipAddress 

' Padding characters. 

-Sin_zero = String(8, vbNullChar) 
End With 
Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, 





If retval <> 0 Then 
Debug.Print 
GoTo Cleanup 























End If 

' Send 

buffer = "GET / HTTP/1. 
"Host: 
"User-Agent: 

retval = send(sock, 








Debug.Print "Sent 


' 





Make the socket 
waiting for input. 
re 


tval 











connection is 


' lost). For brevity, 





Do 





buffer 
retval 





If retval <> 0 And retval <> SOCK 
reply & Left (buffer, 


reply 


End If 





www.vbapi.com" 


non-blocking, 


ioctlsocket (sock, 


recv (sock, 





1" 


Waiting 


FIONBIO, 





Space (4096) 





"Unable to connect!" 





1) 


Read the response from the other system. 
would watch to see if the connection ever times out 





& vbCrLf & vbCrLf 
Len (buffer), 


Len (sockinfo) ) 


an HTTP/GET request for the /index.html file. 
& vbCrLf & _ 
& vbCrLf & _ 

HTTP-Test-—Program" 
ByVal buffer, 
request. 





0) 


for reply..." 


so calls to recv don't halt the program 


A more sophisticated program 


























(i.e., if the 
such code is omitted here. 
ByVal buffer, Len (buffer), 0) 
ET_ERROR Then 
retval) 
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' Process background events so the program doesn't appear to 








DoEvents 


Loop Until retval = 


' Print 
Debug. P 
Debug. P 





' Perform the necessary cleanup at the end. 


Cleanup: 
retval 
retval 

End Sub 





See Also 


socket 


Category 


Winsock 





the response 


0 





from the server. 


rint "Document Retrieved:" 





rint reply 


= closesocket (sock) 


= WSACleanup ( 


Back to the Function list. 





Back to the Reference 


section. 





Last Modified: January 21, 2001 


This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


) 


Go back to the Windows API Guide home page. 





E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 





This page is at http://www.vbapi.com/ref/c/closesocket.html 
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CombineRgn Function 





Declare Function CombineRgn Lib "gdi32.d1ll1" (ByVal hDestRgn As Long, ByVal hSrcRgnl 
As Long, ByVal hSrcRgn2 As Long, ByVal nCombineMode As Long) As Long 























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CombineRgn combines two regions to form a third region. The two regions can be combined using a variety of logical 
operators. Note that the region that receives the combined regions must already be a region -- the function cannot create a new 
one but can change an existing one. 


Return Value 


The function returns one of the following flags specifying the result of the region combination operation: 


ERROR 

An error occured while trying to combine the regions. 
NULLREGION 

The combined region is empty, i.e., null. 
SIMPLEREGION 

The combined region forms a rectangle. 
COMPLEXREGION 

The combined region is not empty but is also not a rectangle. 


Visual Basic-Specific Issues 


None. 


Parameters 


hDestRgn 
A handle to the region to be set to the combination of the two source regions. This region must already have been 
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created, although its contents when passed to the function is irrelevant. 
hSrcRgn1 
The first of the two source regions. 
hSrcRgn2 
The second of the two source regions. 
nCombineMode 
One of the following flags specifying the logical operation to use to combine the two regions: 
RGN_AND 
The combined region is the overlapping area of the two source regions. 
RGN_OR 
The combined region is all the area contained in either of the two source regions, including any overlap. 
RGN_XOR 
The combined region is all of the area contained in either of the two source regions, excluding any overlap. 
RGN_DIFF 
The combined region is all the area of the first source region except for the portion also included in the second 
source region. 
RGN_COPY 
The combined region is identical to the first source region. The second source region is ignored. 


Constant Definitions 

































































Const ERROR = 0 

Const NULLREGION = 1 
Const SIMPLEREGION = 2 
Const COMPLEXREGION = 3 
Const RGN_AND = ] 

Const RGN_OR = 2 

Const RGN_XOR = 3 

Const RGN_DIFF = 4 
Const RGN_COPY = 5 


Example 


' This code is licensed according to the terms and conditions listed here. 





' On window Forml, create overlapping elliptical and rectangular regions. 
' Fill the overlapped area with a dark gray brush; fill the nonoverlapping areas with 
















































































' a light gray brush. 

Dim hRgnl As Long, hRgn2 As Long ' elliptical and rectangular source regions. 
Dim hXorRgn As Long, hAndRgn As Long ' regions set to the non-intersection and 
intersection 

Dim hLightBrush As Long, hDarkBrush As Long ' handles to light gray and dark gray 
brushes 

Dim retval As Long ' return value 

' Create the four regions. The initial settings of hXorRgn and hAndRgn are 
irrelevant. 

hRgnl = CreateBllipticRgn(100, 50, 200, 100) ' bounding rect (100,50)-(200,100) 
hRgn2 = CreateRectRgn (150, 75, 300, 200) ' rectangle (150,75)-(300, 200) 

hXorRgn = CreateRectRgn(0, 0, 0, 0) ' meaningless initialization 
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hAndRgn = CreateRectRgn(0, 0, 0, 0) ' meaningless initialization 








' Now set hAndRgn to the intersection of the two source regions and hXorRgn to 







































































' the non-intersection of the two source regions. 

retval = CombineRgn(hXorRgn, hRgnl, hRgn2, RGN_XOR) " non-intersection 
retval = CombineRgn (hAndRgn, hRgnl, hRgn2, RGN_AND) ' intersection 

" Now get the necessary stock brushes and fill in the two combined regions. 
hLightBrush = GetStockObject (LTGRAY_BRUSH) ' light gray solid brush 
hDarkBrush = GetStockObject (DKGRAY_BRUSH) ' dark gray solid brush 

retval = FillRgn(Forml.hDC, hxXorRgn, hLightBrush) ' fill non-intersection 
retval = FillRgn(Forml.hDC, hAndRgn, hDarkBrush) ' fill intersection 





























' Delete the four regions to free up resources. 
retval = DeleteObject (hRgn1) 














retval = DeleteObject (hRgn2) 
retval = DeleteObject (hXorkRgn) 
retval = DeleteObject (hAndRgn) 





























( 
( 








Category 


Regions 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


Last Modified: December 22, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/c/combinergn.html 











http://216.26.168.92/vbapi/ref/c/combinergn.html (3 of 3) [9/1/2002 5:09:00 PM] 


Windows API Guide: CommDI]gExtendedError Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 





shop.com | 
CommDIgExtendedError Function 
Declare Function CommDlgExtendedError Lib "comdlg32.d11" () As Long 


Platforms: Win 32s, Win 95/98, Win NT 


CommDIgExtendedError returns the error code from the last common dialog box function. This function does not return 
error codes for any other API function; for that, use GetLastError instead. The function's return value is undefined if the last 
common dialog function call was successful. If an error with a common dialog function did occur, the return value is exactly 
one of the following common dialog error flags: 


CDERR_DIALOGFAILURE = & HFFFF 

The function could not open the dialog box. 
CDERR_FINDRESFAILURE = &H6 

The function failed to find the desired resource. 
CDERR_GENERALCODES = &HO 

The error involved a general common dialog box property. 
CDERR_INITIALIZATION = &H2 

The function failed during initialization (probably insufficient memory). 
CDERR_LOADRESFAILURE = &H7 

The function failed to load the desired resource. 
CDERR_LOADSTRFAILURE = &H5 

The function failed to load the desired string. 
CDERR_LOCKRESFAILURE = &H8 

The function failed to lock the desired resource. 
CDERR_MEMALLOCFAILURE = &H9 

The function failed to allocate sufficient memory. 
CDERR_MEMLOCKFAILURE = &HA 

The function failed to lock the desired memory. 
CDERR_NOHINSTANCE = &H4 

The function was not provided with a valid instance handle (if one was required). 
CDERR_NOHOOK = &HB 

The function was not provided with a valid hook function handle (if one was required). 
CDERR_NOTEMPLATE = &H3 

The function was not provided with a valid template (if one was required). 
CDERR_REGISTERMSGFAIL = &HC 

The function failed to successfully register a window message. 
CDERR_STRUCTSIZE = &H1 

The function was provided with an invalid structure size. 
CFERR_CHOOSEFONTCODES = &H2000 

The error involved the Choose Font common dialog box. 
CFERR_MAXLESSTHAMMIN = &H2002 

The function was provided with a maximum font size value smaller than the provided minimum font size. 
CFERR_NOFONTS = &H2001 
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The function could not find any existing fonts. 
FNERR_BUFFERTOOSMALL = &H3003 
The function was provided with a filename buffer which was too small. 
FNERR_FILENAMECODES = &H3000 
The error involved the Open File or Save File common dialog box. 
FNERR_INVALIDFILENAME = &H3002 
The function was provided with or received an invalid filename. 
FNERR_SUBCLASSFAILURE = &H3001 

The function had insufficient memory to subclass the list box. 
FRERR_BUFFERLENGTHZERO = &H4001 

The function was provided with an invalid buffer. 
FRERR_FINDREPLACECODES = &H4000 

The error involved the Find or Replace common dialog box. 
PDERR_CREATEICFAILURE = &H100A 

The function failed to create an information context. 
PDERR_DEFAULTDIFFERENT = &H100C 

The function was told that the information provided described the default printer, but the default printer's actual 

settings were different. 
PDERR_DNDMMISMATCH = &H1009 

The data in the two data structures describe different printers (i.e., they hold conflicting information). 
PDERR_GETDEVMODEFAIL = &H1005 

The printer driver failed to initialize the DEVMODE structure. 
PDERR_INITFAILURE = &H1006 

The function failed during initialization. 
PDERR_LOADDRVFAILURE = &H1004 

The function failed to load the desired device driver. 
PDERR_NODEFAULTPRN = &H1008 

The function could not find a default printer. 
PDERR_NODEVICES = &H1007 

The function could not find any printers. 
PDERR_PARSEFAILURE = &H1002 

The function failed to parse the printer-related strings in WIN.INI. 
PDERR_PRINTERCODES = &H1000 

The error involved the Print common dialog box. 
PDERR_PRINTERNOTFOUND = &H100B 

The function could not find information in WIN.INI about the requested printer. 
PDERR_RETDEFFAILURE = &H1003 

The handles to the data structures provided were nonzero even though the function was asked to return information 

about the default printer. 
PDERR_SETUPFAILURE = &H1001 

The function failed to load the desired resources. 





Example: 
' Give the Open File dialog box an insufficient buffer size. 
Then display the error code provided. 














Dim filebox As OPENFILENAME ' structure that sets the dialog box 
Dim fname As String ' will receive selected file's name 

Dim retval As Long ' return value 

Dim errcode As long ' receives th rror code 
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' Configure how the dialog box will look 

































































filebox.1StructSize = Len (filebox) " the size of the structure 

filebox.hwndOwner = Forml.hWnd ' handle of the form calling the function 
filebox.lpstrTitle = "Open File" ' text displayed in the box's title bar 

' The next line sets up the file types drop-box 

filebox.lpstrFilter = "Text Files" & vbNullChar & "*.txt" & vbNullChar & "All Files" 
& vbNullChar & "*.*" & vbNullChar & vbNullChar 

filebox.lpstrFile = "" ' ERROR: an empty buffer! 

filebox.nMaxFile = 0 ' length of file and pathname buffer 

filebox.lpstrFileTitle = Space (255) ' initialize buffer that receives filename of 
file 

filebox.nMaxFileTitle = 255 ' length of filename buffer 











' Allow only existing files and hide the read-only check box 
ilebox.flags = OFN_PATHMUSTEXIST Or OFN_FILEMUSTEXIST Or OFN_HIDEREADONLY 

















' Execute the dialog box 
retval = GetOpenFileName (filebox) 





If retval = 0 Then " some error occured, or Cancel was pressed 





errcode = CommDlgExtendedError () ' get the error code for GetOpenFileNam 
If errcode = FNERR_BUFFERTOOSMALL Then 
Debug.Print "The buffer provided was too small to hold the filename." 
If errcode = FNERR_INVALIDFILENAME Then 
Debug.Print "An invalid filename was provided." 

' etc. 

End If 
End If 





























See Also: GetLastError 
Category: Common Dialog 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/c/commdlgextendederror.html 
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CompareFileTime Function 








Declare Function CompareFileTime Lib "kernel32.d11" (lpFileTimel As FILETIME, 
lpFileTime2 As FILETIME) As Long 






































Platforms: Win 32s, Win 95/98, Win NT 


CompareFileTime compares two times stored in FILETIME format. The function determines which of the two times, if any, 


comes before the other chronologically. If the first time is earlier than the second time, the function returns -1. If the two times 
are equal, the function returns 0. If the first time is later than the second time, the function returns 1. 


lpFileTimel 

The first of the two times to compare. 
lpFileTime2 

The second of the two times to compare. 


Example: 




















' Determine if file C:\MyProgram\datafile.txt was created before 
' Jan 5, 1999. Note how CreateFile's alternate declare must be used under Win 95/98 

















' see that function's page for more information. 































































































































































































Dim hfile As Long ' receives the handle to the file 

Dim ctime As FILETIME ' receives creation date and time of the file 

Dim atime As FILETIME ' receives last access date and time of the file 

Dim wtime As FILETIME ' receives last write-to date and time of the file 

Dim jantime As SYSTEMTIME ' will be set to Jan 5, 1999 

Dim janfiletime As FILETIME ' will receive analogous time as jantime 

Dim comptimes As Long ' receives comparison of ctime and janfiletime 

Dim retval As Long ' return value 

" Get a handle to the file (note how the alternate declare is used): 

hfile = CreateFileNS ("C:\MyProgram\datafile.txt", GENERIC_READ, FILE_SHARE_ READ, 0, 














































































































OPEN_EXISTING, FILE ATTRIBUTE _ARCHIVE, 0) 

If hfile = -1 Then ' if the file could not be opened 
Debug.Print "Could not open the file C:\MyProgram\datafile.txt." 
End ' abort the program 

End If 

















' Get the various times and dates associated with the file: 
retval = GetFileTime(hfile, ctime, atime, wtime) 

' Load jantime with the date January 5, 1999 at midnight: 
jantime.wMonth = 1: jantime.wDay = 5: jantime.wYear = 1999 
jantime.wHour = 0: jantime.wMinute = 0: jantime.wSecond = 0 
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" Convert jantime into FILETIME format so it can be compared with ctime: 
retval = SystemTimeToFileTime(jantime, janfiletime) 

















" Compare the two times and display the relation: 

comptimes = CompareFileTime(ctime, janfiletime) 

If comptimes = -1 Then Debug.Print "File was created before midnight, January 5, 
1999)" 
If comptimes 0 Then Debug.Prin 
If comptimes = 1 Then Debug.Prin 














"File was created at midnight, January 5, 1999." 
"File was created after midnight, January 5, 1999." 


























cr st 








' Close the file 
retval = CloseHandle (hfile) 











Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/c/comparefiletime.html 
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CompareString Function 








Declare Function CompareString Lib "kernel32.d11" Alias "CompareStringA" (ByVal 
Locale As Long, ByVal dwCmpFlags As Long, ByVal lpStringl As String, ByVal cchCountl 
As Long, ByVal lpString2 As String, ByVal cchCount2 As Long) As Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CompareString compares two strings and determines which one would come first in an alphabetic sort. Although this 
function can use a number of different comparisons, by default it conducts a case-sensitive word sort. In a word sort, all 
symbols except hyphens and apostrophes come before the letter "a" (hyphens and apostrophes are treated differently). The 
function compares strings by first comparing their first characters, then their second characters, etc. until an unequal pair of 
characters is found. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one of the 
following flags specifying the result of the comparison: 
CSTR_LESS_THAN 

The first string is less than the second string (i.e., the first string comes before the second string in alphabetical order). 
CSTR_EQUAL 

The first string is equal to (but not necessarily identical to) the second string. 


CSTR_GREATER_THAN 
The first string is greater than the second string. 


Visual Basic-Specific Issues 


None. 


Parameters 
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Locale 
The locale identifier of the locale to use to compare the strings. This could also be one of the following flags: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
The user's default locale. 
dwCmpFlags 
A combination of the following flags specifying options for the comparison. To use the default comparison, set this 
parameter to 0. 
NORM_IGNORECASE 
Conduct a case-insensitive search. 
NORM_IGNOREKANATYPE 
For Japanese characters, do not differentiate between Hiragana and Katakana characters. 
NORM_IGNORENONSPACE 
Ignore nonspacing characters. 
NORM_IGNORESYMBOLS 
Ignore symbols. 
NORM_IGNOREWIDTH 
Do not differentiate between equivalent single-byte and double-byte characters. 
SORT_STRINGSORT 
Use a string sort instead of a word sort. In a string sort, all symbols, including hyphens and apostrophes, come 





before the letter "a". 

[pString1 

The first string to compare. 
cchCount1 

The length of /pString/. If this is -1, pString] must end in a terminating null character. 
IpString2 

The second string to compare. 
cchCount2 


The length of /pString2. If this is -1, /pString2 must end in a terminating null character. 


Constant Definitions 












































































































































Const CSTR_LESS_THAN = 1 

Const CSTR_EQUAL = 2 

Const CSTR_GREATER_THAN = 3 

Const LOCALE SYSTEM DEFAULT = &H400 
Const LOCALE USER DEFAULT = &H800 
Const NORM_IGNORECASE = &H1 

Const NORM_IGNOREKANATYPE = &H10000 
Const NORM_IGNORENONSPACE = &H2 
Const NORM_IGNORESYMBOLS = &H4 
Const NORM_IGNOREWIDTH = &H20000 
Const SORT_STRINGSORT = &H1000 
Example 


i 


This code is licensed according to the terms and conditions listed here. 


' 


Use a case-senitive, string sort comparison method to alphabetically 
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" sort nine words. 





' pair of 


Dim 
Dim 
Dim 
Dim 





Dim 


words (1 
tempstr As String ' 
oc As 
compval As Long '! 
thread] 


f words; 


To 9 


Intege 


ocale 








' Ge 


t the 
threadlocale 





locale 





i 


f a pair is out of 
' (Compare these results to those 


) As String 


r, 


As Long 


of this thread 











G 





= 


ic As Integer ' 
result of comparison 











" the words to sort 
buffer used to swap strings 


The sorting method simply compares each possible 
alphabetical order, 
from using lstremp for 





counter variables 


D of this thread 





locale II 


(i.e 


tThreadLocale() 




















O 


=? 














f this program). 








' Load the nine strings into the array. 
words (1) Teantt" 
words (2) = "cant" 
words (3) = "cannot" 
words (4) = "pants" 
words (5) = "co-op" 
words (6) = "coop" 
words (7) = "Denver" 
words (8) = "denver" 
words (9) = "denveR" 
' Sort the strings, swapping any pairs which are out of order. 
For oc = 1 To 8 ' first string of the pair 
For ic = oc + 1 To 9 ' second string of the pair 
' Compare the two strings. 
compval = CompareString(threadlocale, SORT_STRINGSORT, words (oc), 


words (ic), 


If compval 
tempstr 
words (o 
words (i 

End If 

Next ic 





Next oc 


" Display the list of 


For oc 





Next oc 


Cc) 
Cc) 


1 To 9 


See Also 


Istremp, Istrcmpi 


Category 


Strings 


Len (words (ic) ) ) 


' If words (oc) is greater, 





CSTR_GR 





KATE 








words (oc) 





Debug.Print words (oc) 


words (ic) 
tempstr 





R_THAN Then 


sorted words. 


swap them. 
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the comparison.) 


Len (words (oc)), 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: December 30, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/c/comparestring.html 
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connect Function 
Declare Function connect Lib "wsock32.dl11" (ByVal s As Long, name As sockaddr, ByVal 











namelen As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


connect establishes a connection between a socket and a network host. The Winsock implementation automatically handles the 
details of the connection, which vary depending on the base protocols being used (e.g., TCP/IP vs. UDP/IP). Once the 
connection is established, data can be sent to and from the network host. 


Return Value 


If successful, the function returns zero. If an error occured, the function returns SOCKET_ERROR (use WSAGetLastError to 
get the error code). 





Visual Basic-Specific Issues 


None. 


Parameters 


A descriptor of the socket to use to connect. The descriptor is obtained by a previous call to socket. 
name 

Information describing the network host to connect to. 
namelen 

The length of the structure passed as name. 


Constant Definitions 
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Const S 





OCKET_ERROR = -1 











Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 


HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 


Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 


called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 
had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the tern 








" Declarations and such needed for 
' (Copy them to the 


Public 





End Typ 
Public 
Integer 





ublic 
ublic 
ublic 
ublic 
ong 
ublic 








Ue UU tg tg 





End Typ 
Public 
Integer 
Public 
As Long 





Type WSADATA 


wVersion As 





(declarations) 





Integer 


wHighVersion As Integer 





szDescription As SI 





the example: 


£ 





section of a module.) 


tring * 257 


szSystemStatus As String * 129 





iMaxSockets 





As Long 


iMaxUdpDg As Long 
lpVendorInfo As Long 


= 





, lpWSAData _ 








As WSADATA) 





As Long 








Const AF_INE 











T = 2 


Const SOCK_STREAM = 1 








Type hostent 





Declare Function gethostbyname Lib 





h_name As Long 
h_aliases As Long 
h_addrtype As Integer 





h_length As 
h_addr_list 
e 

Declare Funct 





Declare Funct 


r — 








Integer 
As Long 


tion htons Lib 





tion socket Lib 


ByVal protocol As Long) As 


Public Type sockaddr 





sin_family As Integer 


Sin_port As 





Integer 


"wsock32.dl11" 








Declare Function WSACleanup Lib "wsock32.d11" () As Long 

















"wsock32.d11" 


( 


( 


ByVal hostshort As 





ByVal af As Long, 





Long 
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Declare Function WSAStartup Lib "wsock32.dll1" (ByVal wVersionRequested As 


"wsock32.d11" (ByVal name As String) As 





Integer) As 





ByVal prototype 
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Sin_addr As Long 
Sin_zero As String * 8 
End Type 
Public Declare Function connect Lib "wsock32.d1ll1" (ByVal s As Long, name As sockaddr, 








ByVal namelen _ 
As Long) As Long 
Declare Function ioctlisocket Lib "wsock32.dll1" (ByVal s As Long, ByVal cmd As Long, 














argp As Long) As Long 
Public Const FIONBIO = &H8004667E 
Public Declare Function send Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 























length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function recv Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 

















length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 

















Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 

As Any, Source _ 
As Any, ByVal Length As Long) 

Public Const SOCKET _ERROR = -1 




















' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val ("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 





























2)) 
End Function 





' xxx Place the following code inside the form window. *** 


Private Sub cmdDownload_Click () 






























































Dim wsockinfo As WSADATA ' info about Winsock 

Dim sock As Long ' the socket descriptor 

Dim pHostinfo As Long ' pointer to info about the host computer 
Dim hostinfo As hostent ' info about the host computer 

Dim plPAddress As Long ' pointer to host's IP address 

Dim ipAddress As Long ' host's IP address 

Dim sockinfo As sockaddr ' settings for the socket 

Dim buffer As String ' buffer for sending and receiving data 
Dim reply As String " accumulates server's reply 

Dim retval As Long ' generic return value 














' Begin a Winsock session. 

retval = WSAStartup (MAKEWORD (2, 2), wsockinfo) 

If retval <> 0 Then 

Debug.Print "Unable to initialize Winsock! --"; retval 
Exit Sub 




















End If 











' Get information about the server to connect to. 
pHostinfo = gethostbyname ("www.vbapi.com") 


If pHostinfo = 0 Then 
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Debug.Print "Unable to resolve host!" 
GoTo Cleanup 

End If 
' Copy information about the server into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 

If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "Couldn't get IP address of www.vbapi.com!" 
GoTo Cleanup 












































End If 

" Get the server's IP address out of the structure. 
CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 
CopyMemory ipAddress, ByVal pIPAddress, 4 




















" Create a socket. 

sock = socket (AF_INET, SOCK_STREAM, 0) 

If sock = SOCKET _ERROR Then 

Debug.Print "Unable to create socket!" 
GoTo Cleanup 



































End If 


' Make a connection to www.vbapi.com:80 (where the web server listens). 
With sockinfo 
' Use Internet Protocol (IP) 


.Sin_family = AF_INET 


























" Connect to port 80. 
-Sin_port = htons (80) 
" Connect to this IP address. 





.Sin_addr = ipAddress 
' Padding characters. 
Sin_zero = String(8, vbNullChar) 








End With 








Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, Len(sockinfo) ) 





If retval <> 0 Then 
Debug.Print "Unable to connect!" 
GoTo Cleanup 





End If 














' Send an HTTP/GET request for the /index.html file. 
buffer = "GET / HTTP/1.1" & vbCrLf & _ 

"Host: www.vbapi.com" & vbCrLf & _ 

"User-Agent: HTTP-Test-Program" & vbCrLf & vbCrLf 
retval = send(sock, ByVal buffer, Len(buffer), 0) 
Debug.Print "Sent request. Waiting for reply..." 



































' Make the socket non-blocking, so calls to recv don't halt the program 
waiting for input. 
retval = ioctlsocket (sock, FIONBIO, 1) 








' Read the response from the other system. A more sophisticated program 
' would watch to see if the connection ever times out (i.e., if the 
connection is 
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' lost). For brevity, such code is omitted here. 
Do 





buffer = Space (4096) 

retval = recv (sock, ByVal buffer, Len (buffer), 0) 

If retval <> 0 And retval <> SOCKET_ERROR Then 
reply = reply & Left (buffer, retval) 


















































End If 

' Process background events so the program doesn't appear to freeze. 
DoEvents 

Loop Until retval = 0 

















' Print the response from the server. 
Debug.Print "Document Retrieved:" 
Debug.Print reply 

















' Perform the necessary cleanup at the end. 
Cleanup: 

retval = closesocket (sock) 

retval = WSACleanup () 
End Sub 





Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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CopyFile Function 


Declare Function CopyFile Lib "kernel32.d11" Alias "CopyFileA" (ByVal 
lpExistingFileName As String, ByVal lpNewFileName As String, ByVal 
bFailIfExists As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 
CopyFile copies a file from one location to another, just like copying a file in Windows Explorer or in 


some other way. Depending on the value for bFaillfExists, it will either overwrite the target file if it 
already exists, or will fail. The function retuns 1 if successful, or 0 if an error occured. 


lpExisting FileName 

The source file; i.e., the file to copy from. 
lpNewFileName 

The target file; i.e., the new file to create that will be the copy. 
bFaillfExists 


If 0, the function will overwrite IpNewFileName if it already exists. If non-zero, the function will 
instead fail. 


Example: 


' Copy the file C:\MyStuff\temp.txt to C:\Junk\buffer.txt. 
' Do not overwrite C:\Junk\buffer.txt if it already exists. 
Dim retval As Long ' return value 


' copy the file 
retval = CopyFile("C:\MyStuff\temp.txt", "C:\Junk\buffer.txt", 1) 
If retval = 0 Then ' failure 


Debug.Print "Copy failed -- C:\Junk\buffer.txt already exists. 
Else ' success 

Debug.Print "Copy succeeded." 
End If 


See Also: MoveFile 
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Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/c/copyfile.html 


http://216.26.168.92/vbapi/ref/c/copyfile.html (2 of 2) [9/1/2002 5:10:37 PM] 


Windows API Guide: CopyMemory Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





CopyMemory Function 





Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination As 
Any, Source As Any, ByVal Length As Long) 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


CopyMemory, as far as the Windows API is concerned, is perfectly identical to the MoveMemory function; in fact, they 
actually are the same function! CopyMemory moves the contents of a portion of memory from one location to another. 
The two locations are identified by pointers to the memory addresses. After the copy, the original contents in the source 


are set to zeros. 


Return Value 


CopyMemory does not return a value. 


Visual Basic-Specific Issues 


A pointer to any variable can be automatically generated merely be passing that variable as either Destination or Source. 
However, if either a String or a Long holding the desired memory address is passed, the By Val keyword must preceed it. 


Parameters 


Destination 

A pointer to the memory address to use as the target, which receives the transfered data. 
Source 

A pointer to the memory address to use as the source, which initially holds the data to be transfered. 
Length 

The number of bytes of data to copy from the source memory location to the target memory location. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Transfer the contents of one byte array to another. After the "copy", 
" the contents of the source array are set to 0. 


Dim source(0 To 9) As Byte ' source array of 10 bytes 
Dim target(0 To 9) As Byte ' similarly sized target array 
Dim c As Integer ' counter variable 


' Fill the source array with some information. 





For c = 0 To 9 ' loop through each element 
source(c) = c ' set each element's value to its index 
Next c 


' Transfer the data from the target array to the source array. Note how pointers 
' are implied merely by passing the arrays as usual. 
CopyMemory target (0), source(0), 10 ' copy all 10 bytes 


' Verify that the contents were transfered. 
For c = 0 To 9 

Debug.Print target(c); ' this will now contain the information 
Next c 


See Also 


MoveMemory 


Category 


Memory 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: July 28, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information 


Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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CopyRect Function 


Declare Function CopyRect Lib "user32.d1ll1" (lpDestRect As RECT, 
lpSourceRect As RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


CopyRect sets one rectangle equal to another. This is done by duplicating all of the source rectangle's 
member values to the corresponding ones in the target rectangle. This is faster than setting all four values 
manually in your code. The function returns 0 if an error occured, or 1 if successful. 


lpDestRect 

The target rectangle to set. 
IpSourceRect 

The source rectangle. 


Example: 


" Set the source and target rectangels equal to the rectangle 
' of the window by copying the source to the target 
Dim source As RECT, target As RECT ' source & target rectangles 


Dim retval As Long ' return value 


' Get the rectangle of Forml into source 
retval = GetWindowRect (Forml.hWnd, source) 





' Copy source into target 
retval = CopyRect (target, source) 


See Also: EqualRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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CoTaskMem Free Function 








Declare Sub CoTaskMemFree Lib "ole32.dll1" (ByVal pv As Long) 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


CoTaskMemFree frees some types of blocks of allocated memory. This function will free the memory associated with a 
pointer to an ITEMIDLIST structure (a.k.a. a PIDL) which was created by a Windows shell API function. This function must 
be used on such blocks of memory to free system resources. 





Return Value 


CoTaskMemFree does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


pv 
A pointer to the memory block to free. 


Example 


This code is licensed according to the terms and conditions listed here. 








" Open the Browse for Folder dialog box and display both the display name and 




















" the actual name of the folder (if it is not a virtual folder). Any folder under My 
Computer 
' may be selected. 
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Dim bi As BROWSEINFO ' structure passed to the function 








Dim pidl As Long ' PIDL to the user's selection 
Dim physpath As String ' string used to temporarily hold the physical path 
Dim retval As Long ' return value 


























Initialize the structure to be passed to the function. 

bi.hwndOwner = Forml.hWnd ' window Forml is the owner of the dialog box 
' Specify the My Computer virtual folder as the root 
retval = SHGetSpecialFolderLocation (Forml.hWnd, CSIDL_DRIVES, bi.pidlRoot) 
' Make room in the buffer to get the [virtual] folder's display name 
bi.pszDisplayName = Space (260) 





















































bi.lpszTitle = "Please choose a folder." ' Message displayed to the user 
bi.ulFlags = 0 ' no flags are needed here 

bi.lpfn = 0 ' no callback function is being used 

bi.lParam = 0 ' not needed 

bi.iImage = 0 ' this will be set by the function 




















' Open the Browse for Folder dialog box. 
pidl = SHBrowseForFolder (bi) 

















' If the user selected something, display its display name 
' and its physical location on the system. 
If pidl <> 0 Then 
' Remove the empty space from the display name variable. 
bi.pszDisplayName = Left(bi.pszDisplayName, InStr(bi.pszDisplayName, vbNullChar) - 
1) 
































Debug.Print "The user selected: "; bi.pszDisplayName 

' If the folder is not a virtual folder, display its physical location. 

physpath = Space (260) ' make room in the buffer 

retval = SHGetPathFromIDList (pidl, physpath) 

If retval = 0 Then 

Debug.Print "Physical Location: (virtual folder)" 

lse 
' Remove the empty space and display the result. 

physpath = Left (physpath, InStr(physpath, vbNullChar) - 1) 

Debug.Print "Physical Location: "; physpath 

End If 

' Free the pidl returned by the function. 
CoTaskMemFree pidl 

End If 


















































lka! 






























































' Whether successful or not, free the PIDL which was used to 
' identify the My Computer virtual folder. 
CoTaskMemFree bi.pidlRoot 





Category 


OLE 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/c/cotaskmemfree.html 








http://216.26.168.92/vbapi/ref/c/cotaskmemfree.html (3 of 3) [9/1/2002 5:11:04 PM] 


Windows API Guide: CreateCursor Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 








shop.com | 
CreateCursor Function 
Declare Function CreateCursor Lib "user32.dl1" (ByVal hInstance As Long, ByVal 








nXhotspot As Long, ByVal nYhotspot As Long, ByVal nWidth As Long, ByVal nHeight As 
Long, lIpANDbitPlane As Any, lpXORbitPlane As Any) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


CreateCursor creates a new cursor. Its image is formed by using an AND mask and a XOR mask provided by the function, 
which are used to place the cursor's image wherever it appears. The AND and XOR masks can be provided using any 
numeric array, such as a Byte array (as the example below uses). The function also specifies the cursor's hotspot, the exact 
pixel which is considered to be the location of the cursor (such as the exact tip of the arrow cursor). Note that it is usually a 
better idea to put cursors into some sort of resource or separate file and load them instead of hard-wiring the cursors into the 
application code via this function. (This is because this function relies on creating a cursor compatible with the display 
device, instead of generating one from a file or resource which is.) Of course, the cursor size must be one supported by the 
system; use GetSystemMetrics to check. The cursor created by this function must later be destroyed by using 
DestroyCursor. The function returns 0 if an error occured, or a handle to the newly created cursor if successful. 


hInstance 
The instance handle of the application which is calling the function. 
nXhotspot 
The x-coordinate of the cursor's hotspot, relative to the cursor's upper-left corner. 
nYhotspot 
The y-coordinate of the cursor's hotspot, relative to the cursor's upper-left corner. 
nWidth 
The width in pixels of the cursor. 
nHeight 
The height in pixels of the cursor. 
IpANDbitPlane 
An array holding the AND mask for the cursor's image. 
IpXORbitPlane 
An array holding the XOR mask for the cursor's image. 


Example: 


Create a 32x32 color cursor shaped somewhat like a yin-yang symbol. 

' (The bit masks come from Microsoft's documentation on the API cursors function, 
just to 

' give them their due credit.) Note how the masks are loaded into the arrays. The 


new 
' 








cursor is then set to be the cursor for 10 seconds. 
Dim hnewcursor As Long ' newly created cursor 
Dim holdcursor As Long ' receives handle of default cursor 
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Dim andbuffer As String, xorbuffer As String ' buffers for masks 
Dim andbits(0 To 127) As Byte ' stores the AND mask 

Dim xorbits(0 To 127) As Byte ' stores the XOR mask 

Dim c As Integer, retval As Long ' counter and return value 











' Unfortunately, VB does not provide a nice way to load lots of information into an 
array. 

' To load the AND and XOR masks, we put the raw hex values into the string buffers 
' and use a loop to convert the hex values into numeric values and load them into 

' the elements of the array. Yes, it's ugly, but there's no better way. Note the 































































































' use of the line-continuation character here. Each sequence of eight hex 
' characters represents one line in the 32x32 cursor. 
andbuffer = "FFFC3FFEF" & "FFCOIFFF" & "FFOO3FFF" & "FEOOFFFF" & _ 
"PU7OLFFFE" & "“FOO3FFFE" & "FOO3FFFF" & "“EOOV7FFFF" & _ 
"COO7FFFE" & "“COOFFFFE" & "800FFFFF" & "800FFFFF" & _ 
"8007FFFF" & "8007FFFF" & "QOO3FFFF" & "OQOQOOFFFF" & _ 
"OOOO7FFF" & "QOOOIFFF" & "QOOOOFFF" & "80000FFF" & _ 
"800007FF" & "800007FF" & "COOOO7FF" & "COOOOFFF" & _ 
"EOOOOFFF" & "FOOOIFFF" & "FOOOIFFF" & "F8003FFF" & _ 
"PREOOVFFE" & "“FFOOFFFE" & "FFC3FFFF" & "FFFFFFFEF" 
xorbuffer = "00000000" & "O003C000" & "003F0000" & "OOFEOOOO" & _ 
"OEFCOOOO" & "O7F80000" & "O7F80000" & "OFF00000" & _ 
"IFF00000" & "1FE00000" & "3FE00000" & "3FE00000" & _ 
"3FF00000" & "7FF00000" & "7FF80000" & "7FFC0000" & _ 
"7FFF0000" & "7FFF8000" & "7FFFEOOO" & "3FFFEOOO" & _ 
"3FC7F000" & "3F83F000" & "1F83F000" & "1F83E000" & _ 
"OFC7EO00" & "O7FFC000" & "O7FFC000" & "O1FF8000" & _ 
"OOFFOOOO" & "003C0000" & "00000000" & "00000000" 
' Now load these hex values into the proper arrays. 
For c = 0 To 127 
andbits (c) = "&H" & Mid(andbuffer, 2 * c + 1) 
xorbits(c) = "&H" & Mid(xorbuffer, 2 * c + 1) 
Next c 
' Finally, create this cursor! The hotspot is at (19,2) on the cursor. 





hnewcursor = CreateCursor (App.hInstance, 19, 2, 32, 32, andbits (0), xorbits(0)) 
' Set the new cursor as the current cursor for 10 seconds and then switch back. 





holdcursor = SetCursor(hnewcursor) ' change cursor 
Sleep 10000 ' wait for 10 seconds 
retval = SetCursor(holdcursor) ' change cursor back 





' Destroy the new cursor. 
retval = DestroyCursor (hnewcursor) 











See Also: DestroyCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/c/createcursor.html 
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CreateDC Function 





Declare Function CreateDC Lib "gdi32.dll1" Alias "CreateDCA" (ByVal lpszDriver As 
String, ByVal lpszDevice As String, ByVal lpszOutput As Long, lpInitData As Any) As 
Long 
































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


CreateDC creates a device context to a given object. The object is identified by its name. When you are finished using the 
device context in your program, use the DeleteDC function to destroy it. Do not use ReleaseDC with device contexts created 
by this function! 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a handle to the newly created device context. 


Visual Basic-Specific Issues 


When passing 0 for /pInitData, the expression ByVal CLng(0) must be used. 


Parameters 


IpszDriver 
This string should normally be empty, except for using "DISPLAY" to reference the display driver. Windows NT, 
2000: This could also be "WINSPOOL'" to reference the print spooler. 


lpszDevice 

The name of the device to create a device context for. 
lpszOutput 

Reserved -- set to 0. 
IpInitData 


If desired, a DEVMODE structure holding device initialization information for the device. To use the default 
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initialization, set this to 0. 


Example: 


' Print out a page with an ellipse drawn with a thickened black 





' pen on it. The page is 








printed on the computer's default printer. 





' The following are special declarations needed to allow string 











' manipulation functions to use pointers to strings. 





Declare Function lstrcpy Lib "kernel32.d1ll1" A 





ias "lstrcpyA" (ByVal lpStringl As 














As Long 


' Variable declarations 











im buffer(0 To 3076 / 4) 
im pi2 As PRINTER INFO 2 
im printret As Long ' r 
im spaceneeded As Long 



































String, ByVal lpString2 As Long) As Long 
Declare Function lstrien Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString As Long) 




















Dim hPrintDC As Long ' handle to the printer's device context 
Dim di As DOCINFO ' information about the document to print 
im hPen As Long ' handle to the pen to draw the ellipse with 
im hOldPen As Long ' handle to the printer's previously selected pen 





As Long ' 3076-byte buffer 
' receives info about the default printer 














ceives the number of printers returned from EnumPrinters 














' receives space requires for EnumPrinters 





im retval As Long ' return value 





Get the device and driver names of the default printer. For a more detailed 








' description of the semi-confusing code below, consult the 


' EnumPrinters page. 




















retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 2, buffer(0), 3076, spaceneeded, 























printret) 
If retval = 0 Then 
Debug.Print "No default 


printer is configured." 

















End ' abort the program 
End If 
' Copy the device and driver names to the structure. All the 


' other information retrieved is not needed and is omitted here. 
pi2.pPrinterName = Space (lstrlen (buffer (1))) 








retval = lstrcpy(pi2.pPrinterName, buffer ( 





pi2.pDriverName = Space (lstrlien (buffer (4) 











" Create a device context 


) 
retval = lstrcpy(pi2.pDriverName, buffer (4 


)) 




















1 
) 
)) 


to the printer, using its default initialization. 








hPrintDC = CreateDC("", pi2.pPrinterName, 0, ByVal CLng(0)) 
" Create a solid black brush with a thickness of 5. 
hPen = CreatePen(PS_SOLID, 5, RGB(0, 0, 0)) 






































' Load information about the document to print into the structure. 
di.cbSize = Len (di) " size of structure 

di.lpszDocName = "Printer API Demonstration" ' name of document 
di.lpszOutput = 0 ' do not print to a file 

di.lpszDatatype = "" ' data type of file doesn't apply 
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di.fwType = 0 





" no additional iní 


job. 








Doc (hPrint 











' Begin the print 
retval = Start 
' Begin the first 











retval = StartPage (hPrin 
' Select the pen 
SelectObject (h 


holdPen = 

















DC, di) 
and only page to print. 
tDC) 


for use with the printer. 
PrintDC, hPen) 





Formation 


' Draw an ellipse with bounding rectangle corners 





retval = 








Ellipse (hPrintDC, 


1000, 


1500, 





2000, 


(1000,1500)- (2000, 3000) 





3000) 


' Restore the printer's previously selected pen. 
DC, hOldPen) 


retval 





< 


' End in 
retval = 














' End informat 


ormation about 
EndPage (hPrintDC) 





= SelectObject (hPrint 








ion about 

















retval = 








EndDoc (hPrintDC 


) 





the document. 


the first and only page. 


' The printer will now begin printing the document. 





" Delete 








retval = 

















" Delete 
retval = 








See Also 


DeleteDC 


Category 


Devices 











the pen created for drawing. 
DeleteObject (hPen) 
the device cont 
DeleteDC (hPrint 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





Last Modified: November 6, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 





This page is at http://www.vbapi.com/ref/c/createdc.html 
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CreateDirectory Function 


Declare Function CreateDirectory Lib "kernel32.d1l1" Alias 
"CreateDirectoryA" (ByVal lpPathName As String, lpSecurityAttributes As 
SECURITY ATTRIBUTES) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreateDirectory creates a new directory on a disk. It also allows you to specify the security attributes of the 
newly created directory, if the operating system supports it. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpPathName 
The name of the new directory to create. 
IpSecurityAttributes 


http://216.26.168.92/vbapi/ref/c/createdirectory.html (1 of 2) [9/1/2002 5:11:37 PM] 


Windows API Guide: CreateDirectory Function 


Windows NT, 2000: The security attributes to assign to the newly created directory. Windows 95, 98, 
CE: This parameter is ignored. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Create the new directory C:\Dummy\NewDir and 
' give it default security attributes. 
Dim secattr As SECURITY ATTRIBUTES ' security attributes structure 

















Dim retval As Long ' return value 


" Set the desired security attributes 











secattr.nLength = Len(secattr) ' size of the structure 
secattr.lpSecurityDescriptor = 0 ' default (normal) level of security 
secattr.bInheritHandle = 1 ' this is the default setting 





' Create the directory. 
retval = CreateDirectory("C:\Dummy\NewDir", secattr) 


See Also 
CreateDirectoryEx, RemoveDirectory 
Category 

Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: March 19, 2000 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/c/createdirectory.html 
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CreateDirectoryEx Function 


Declare Function CreateDirectoryEx Lib "kernel32.d11" Alias 
"CreateDirectoryExA" (ByVal lpTemplateDirectory As String, ByVal lpNewDirectory 
As String, lpSecurityAttributes As SECURITY ATTRIBUTES) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


CreateDirectoryEx creates a new directory on a disk. It also allows you to specify the security attributes of the newly 
created directory, if the operating system supports it. The newly created directory will inherit most of its attributes 
(except security) from a template directory specified by the function. For example, the new directory will have the 
same file attributes as the template directory. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pTemplateDirectory 

The name of the directory to use as an attribute template for creating the new directory. 
lpNewDirectory 

The name of the new directory to create. 
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IpSecurityAttributes 
Windows NT, 2000: The security attributes to assign to the newly created directory. Windows 95, 98, CE: 
This parameter is ignored. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Create the new directory C:\Dummy\NewDir and 








' give it default security attributes. It will inherit its properties from the 
' directory C:\Recycled (the "Recycle Bin") -- although this won't be another 

' recycle bin, it will have the Hidden and System attributes. 

Dim secattr As SECURITY ATTRIBUTES ' security attributes structure 

Dim retval As Long ' return value 


' Set the desired security attributes 


secattr.nLength = Len(secattr) ' size of the structure 
secattr.lpSecurityDescriptor = 0 ' default (normal) level of security 
secattr.bInheritHandle = 1 ' this is the default setting 


' Create the directory, using C:\Recycled as the template. 
retval = CreateDirectoryEx("C:\Recycled", "C:\Dummy\NewDir", secattr) 


See Also 


CreateDirectory, RemoveDirectory 


Category 


Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: March 19, 2000 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/c/createdirectory.html 
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CreateEllipticRgn Function 


Declare Function CreateEllipticRgn Lib "gdi32.d1l1" (ByVal X1 As Long, ByVal Y1 
As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


CreateEllipticRgn creates an elliptically-shaped region. The ellipse which forms the region is specified by the 
bounding rectangle defined by the coordinates passed to the function. The bounding rectangle is the smallest possible 
rectangle which can fit around the ellipse. The function returns a handle to the newly created region if successful, or 0 
if an error occured. 


- The x-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
É The y-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
5 The x-coordinate of the lower-right corner of the ellipse's bounding rectangle. 
= The y-coordinate of the lower-right corner of the ellipse's bounding rectangle. 


Example: 


' Invert the pixels within an elliptical region on window Forml. The 
' elliptical region has a bounding rectangle of (20,30)-(150,110). 
Dim hrgn As Long ' handle to the region to invert 

Dim retval As Long ' return value 


' Create the elliptical region to invert and get a handle to it. 

hrgn = CreateEllipticRgn (20,30,150,110) ' bounding rectangle (20,30)-(150,110) 
' Invert that region in window Forml. 

retval = InvertRgn(Forml.hDC, hrgn) 

" Delete the region to free up resources. 

retval = DeleteObject (hrgn) 





See Also: CreateEllipticRgnIndirect 
Category: Regions 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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CreateEllipticRgnindirect Function 


Declare Function CreateEllipticRgnIndirect Lib "gdi32.dl1" (lpRect As RECT) 
As Long 


Platforms: Win 32s, Win 95/98, Win NT 


CreateEllipticRgn creates an elliptically-shaped region. The ellipse which forms the region is specified by the 
bounding rectangle defined by the rectangle structure passed to the function. The bounding rectangle is the 
smallest possible rectangle which can fit around the ellipse. The function returns a handle to the newly created 
region if successful, or 0 if an error occured. 


lpRect 
The bounding rectangle of the ellipse which forms the region. 


Example: 

' Invert the pixels within an elliptical region within window Forml. The 
' elliptical region has a bounding rectangle of (20, 30)-(150,110) 

Dim hrgn As Long ' handle to the elliptical region 


Dim bounding As RECT ' bounding rectangle 
Dim retval As Long ' return value 


' Load the coordinates of the bounding rectangle into the structure. 

retval = SetRect (bounding, 20, 30, 150, 110) ' bounding = (20,30)-(150,110) 
' Create the elliptical region from this bounding rectangle. 

hrgn = CreateEllipticRgnIndirect (bounding) 

' Invert the pixels on Forml within the region. 

retval = InvertRgn(Forml.hDC, hrgn) 





' Delete the region to free up resources. 
retval = DeleteObject (hrgn) 











See Also: CreateEllipticRgn 
Category: Regions 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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CreateFile Function 








Declare Function CreateFile Lib "kernel32.d1l1" Alias "CreateFileA" (ByVal lpFileName 
As String, ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, 
lpSecurityAttributes As Any, ByVal dwCreationDisposition As Long, ByVal 
dwFlagsAndAttributes As Long, ByVal hTemplateFile As Long) As Long 






































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreateFile creates or opens a console, communications resource, directory (can only open), disk devices (Windows NT, 2000 
only), files, mailslots, and pipes. Obviously, files are the most common thing opened by the function. The object opened can 
then be read from or written to, as the access level allows. After your program is finished using the handle generated by the 





function, it must call CloseHandle to close the open object. 


Return Value 


If an error occured, the function returns -1 (use GetLastError to get the error code). If successful, the function returns a handle 
to the opened or created file or other object. 


Visual Basic-Specific Issues 


When passing 0 as the /pSecurityAttributes parameter, the expression ByVal CLng(0) must be used to pass the zero correctly. 
See the example for a demonstration. 


Parameters 


lpFileName 
The name of the file or other allowed object to create or open. 
dwDesiredAccess 
A combination of the following flags (if any) specifying the amounts of read/write access to the file or other object: 
GENERIC_READ 
Allow the program to read data from the file or other object. 
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GENERIC_WRITE 
Allow the program to write data to the file or other object. 
dwShareMode 
A combination of the following flags (if any) specifying the amounts of read/write access to grant other programs 
attempting to access the file or other object while your program still has it open: 
FILE_SHARE_ READ 
Allow other programs to read data from the file or other object. 
FILE_SHARE_WRITE 
Allow other programs to write data to the file or other object. 
IpSecurityAppributes 
Windows NT, 2000: A SECURITY_ATTRIBUTES structure specifying the security attributes to give the created or 
opened file or other object. Windows 95, 98, CE: This parameter must be 0. 
dwCreationDisposition 
Exactly one of the following flags specifying how and when to create or open the file or other object depending if it 
already does or does not exist: 
CREATE_ALWAYS 
Create a new file or other object. Overwrite the file or other object (i.e., delete the old one first) if it already 
exists. 
CREATE_NEW 
Create a new file or other object. The function fails if the file or other object already exists. 
OPEN_ALWAYS 
Open an existing file or other object. If the file or other object does not exist, it will be created. 
OPEN_EXISTING 
Open an existing file or other object. The function fails if the file or other object does not exist. 
TRUNCATE_EXISTING 
Open an existing file or other object and delete its contents. The function fails if the file or other object does not 
exist. 
dwFlagsAndAttributes 
The combination of the following flags specifying both the file attributes of a newly created file and other options for 
creating or opening the file. One flag specifying the file attributes must be included. 
FILE_ATTRIBUTE_ARCHIVE 
An archive file (which most files are). 
FILE_ATTRIBUTE_HIDDEN 
A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL 
An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY 
A read-only file. 
FILE_ATTRIBUTE_SYSTEM 
A system file, used exclusively by the operating system. 
FILE_FLAG_DELETE_ON_CLOSE 
Delete the file once it is closed. 
FILE_FLAG_NO_BUFFERING 
Do not use any buffers or caches. If used, the following things must be done: access to the file must begin at 
whole number multiples of the disk's sector size; the amounts of data accessed must be a whole number multiple 
of the disk's sector size; and buffer addresses for I/O operations must be aligned on whole number multiples of 
the disk's sector size. 
FILE_FLAG_OVERLAPPED 
Allow asynchronous I/O; i.e., allow the file to be read from and written to simultaneously. If used, functions that 
read and write to the file must specify the OVERLAPPED structure identifying the file pointer. (Windows 95, 
98, CE: Overlapped files are not supported, although other overlapped objects are.) 
FILE_FLAG_POSIX_SEMANTICS 
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Allow file names to be case-sensitive. 

FILE_FLAG_RANDOM_ACCESS 

Optimize the file cache for random access (skipping around to various parts of the file). 

FILE_FLAG_SEQUENTIAL_SCAN 

Optimize the file cache for sequential access (starting at the beginning and continuing to the end of the file). 

FILE_FLAG_WRITE_THROUGH 

Bypass any disk cache and instead read and write directly to the file. 

hTemplate File 
A handle to an open file to copy the attributes of, or 0 to not copy the attributes of any open file. 


Constant Definitions 




































































































































































































































































































































































Const GENERIC_READ = &H80000000 

Const GENERIC_WRITE = &H40000000 

Const FILE SHARE READ = &H1 

Const FILE SHARE WRITE = &H2 

Const CREATE ALWAYS = 2 

Const CREATE _ NEW = 

Const OPEN_ALWAYS = 4 

Const OPEN_EXISTING = 8 

Const TRUNCATE_EXISTING = 5 

Const FILE _ATTRIBUTE_ARCHIVE = &H20 

Const FILE _ATTRIBUTE_HIDDEN = &H2 

Const FILE ATTRIBUTE NORMAL = &H80 

Const FILE ATTRIBUTE READONLY = &H1 

Const FILE ATTRIBUTE SYSTEM = &H4 

Const FILE FLAG DELETE _ON_CLOSE = &H4000000 
Const FILE_FLAG NO_BUFFERING = &H20000000 
Const FILE FLAG OVERLAPPED = &H40000000 
Const FILE FLAG POSIX _SEMANTICS = &H1000000 
Const FILE FLAG RANDOM_ACCESS = &H10000000 
Const FILE FLAG SEQUENTIAL SCAN = &H8000000 
Const FILE_FLAG WRITE _THROUGH = &H80000000 
Example 


' This code is licensed according to the terms and conditions listed here. 





' Display the date on which 


" created. Note how th 


hFile 
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mtime 
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As Long 
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' First, 
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hFile 





" return value 
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OPEN_EXISTING, FILE _ATTRIBUTE_ARCHIVE, 0) 

If hFile = -1 Then 
Debug.Print "Could not open the file successfully -- aborting." 
End ' terminate the program 

End If 











' Next, get the creation, last-access, and last-modification times. 
retval = GetFileTime(hFile, ctime, atime, mtime) 











" Convert the creation time to the local time zone. 
retval = FileTimeToLocalFileTime(ctime, ctime) 

" Convert the FILETIME format to the SYSTEMTIME format. 
retval = FileTimeToSystemTime(ctime, thetime) 









































' Display the date of creation of the file to the user. 
Debug.Print "The file was created on "; thetime.wMonth; "-"; thetime.w 
thetime.wYear 














' Close the file to free up resources. 
retval = CloseHandle (hFile) 





Category 


Files 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





Last Modified: September 30, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/c/createfile.html 
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CreateFont Function 


Declare Function CreateFont Lib "gdi32.dll" Alias "CreateFontA" (ByVal nHeight As 
Long, ByVal nWidth As Long, ByVal nEscapement As Long, ByVal nOrientation As Long, 
ByVal fnWeight As Long, ByVal fdwItalic As Long, ByVal fdwUnderline As Long, ByVal 
fdwStrikeOut As Long, ByVal fdwCharSet As Long, ByVal fdwOutputPrecision As Long, 
ByVal fdwClipPrecision As Long, ByVal fdwQuality As Long, ByVal fdwPitchAndFamily As 
Long, ByVal lpszFace As String) As Long 


















































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


CreateFont creates a font object, which allows a font with given attributes to be used to draw text on a device. The font 
created by the function is the one which most closely matches the attributes of the logical font information passed via the 
numerous parameters. After your program is finished using the font, it must be deleted by using DeleteObject. 





Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a handle to the font just created. 


Visual Basic-Specific Issues 


None. 


Parameters 


nHeight 
The height of the font's character cell, in logical units (also known as the em height). If positive, the font mapper 
converts this value directly into device units and matches it with the cell height of the possible fonts. If 0, the font 
mapper uses a default character height. If negative, the font mapper converts the absolute value into device units and 
matches it with the character height of the possible fonts. 
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nWidth 
The average width of the font's characters. If 0, the font mapper tries to determine the best value. 
nEscapement 
The angle between the font's baseline and escapement vectors, in units of !/1ọ degrees. Windows 95, 98: This must be 
equal to [fOrientation. 
nOrientation 
The angle between the font's baseline and the device's x-axis, in units of !/;) degrees. Windows 95, 98: This must be 


equal to [fEscapement. 
jnWeight 
One of the following flags specifying the boldness (weight) of the font: 
FW_DONTCARE 
Default weight. 
FW_THIN 
Thin weight. 
FW_EXTRALIGHT 
Extra-light weight. 
FW_ULTRALIGHT 
Same as FW_EXTRALIGHT. 
FW_LIGHT 
Light weight. 
FW_NORMAL 
Normal weight. 
FW_REGULAR 
Same as FW_NORMAL. 
FW_MEDIUM 
Medium weight. 
FW_SEMIBOLD 
Semi-bold weight. 
FW_DEMIBOLD 
Same As FW_SEMIBOLD. 
FW_BOLD 
Bold weight. 
FW_EXTRABOLD 
Extra-bold weight. 
FW_ULTRABOLD 
Same as FW_EXTRABOLD. 
FW_HEAVY 
Heavy weight. 
FW_BLACK 
Same as FW_HEAVY. 
fdwitalic 
A non-zero value if the font is italicized, O if not. 
fdwUnderline 
A non-zero value if the font is underlined, 0 if not. 
fdwStrikeOut 
A non-zero value if the font is striked out, 0 if not. 
fdwCharSet 
Exactly one of the following flags specifying the character set of the font: 
ANSI_CHARSET 
ANSI character set. 
ARABIC_CHARSET 
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Windows NT, 2000: Arabic character set. 
BALTIC_CHARSET 
Windows 95, 98: Baltic character set. 
CHINESEBIGS_CHARSET 
Chinese Big 5 character set. 
DEFAULT_CHARSET 
Default character set. 
EASTEUROPE_CHARSET 
Windows 95, 98: Eastern European character set. 
GB2312_CHARSET 
GB2312 character set. 
GREEK_CHARSET 
Windows 95, 98: Greek character set. 
HANGEUL_CHARSET 
HANDEUL character set. 
HEBREW_CHARSET 
Windows NT, 2000: Hebrew character set. 
JOHAB_CHARSET 
Windows 95, 98: Johab character set. 
MAC_CHARSET 
Windows 95, 98: Mac character set. 
OEM_CHARSET 
Original equipment manufacturer (OEM) character set. 
RUSSIAN_CHARSET 
Windows 95, 98: Russian character set. 
SHIFTJIS_CHARSET 
ShiftJis character set. 
SYMBOL_CHARSET 
Symbol character set. 
THAI_CHARSET 
Windows NT, 2000: Thai character set. 
TURKISH_CHARSET 
Windows 95, 98: Turkish character set. 
fdwOutPrecision 
Exactly one of the following flags specifying the desired precision (closeness of the match) between the logical font 
ideally described by the structure and the actual logical font. This value is used by the font mapper to produce the 
logical font. 
OUT_DEFAULT_PRECIS 
The default font mapping behavior. 
OUT_DEVICE_PRECIS 
Choose a device font if there are multiple fonts in the system with the same name. 
OUT_OUTLINE_PRECIS 
Windows NT, 2000: Choose a TrueType or other outline-based font. 
OUT_RASTER_PRECIS 
Choose a raster font if there are multiple fonts in the system with the same name. 
OUT_STRING_PRECIS 
Raster font (used for enumeration only). 
OUT_STROKE_PRECIS 
Windows 95, 98: Vector font (used for enumeration only). Windows NT, 2000: TrueType, outline-based, or 
vector font (used for enumeration only). 
OUT_TT_ONLY_PRECIS 
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Choose only a TrueType font. 
OUT_TT_PRECIS 
Choose a TrueType font if there are multiple fonts in the system with the same name. 
fdwClipPrecision 
Exactly one of the following flags specifying the clipping precision to use when the font's characters must be clipped: 
CLIP_DEFAULT_PRECIS 
The default clipping behavior. 
CLIP_EMBEDDED 
This flag must be set for an embedded read-only font. 
CLIP_LH_ANGLES 
The direction of any rotations is determined by the coordinate system (or else all rotations are 
counterclockwise). 
CLIP_STROKE_PRECIS 
Raster, vector, or TrueType font (used for enumeration only). 
fdwQuality 
Exactly one of the following flags specifying the output quality of the logical font as compared to the ideal font: 
ANTIALIASED_ QUALITY 
Windows 95, 98, NT 4.0 or later, 2000: The font is always antialiased if possible. 
DEFAULT_QUALITY 
The default quality: the appearance of the font does not matter. 
DRAFT_QUALITY 
The appearance of the font is less important then in PROOF_QUALITY. 
NONANTIALIASED_ QUALITY 
Windows 95, 98, NT 4.0 or later, 2000: The font is never antialiased. 
PROOF_QUALITY 
The quality of the appearance of the font is more important than exactly matching the specified font attributes. 
fdwPitchAndFamily 
A bitwise OR combination of exactly one *_PITCH flag specifying the pitch of the font and exactly one FF_* flag 
specifying the font face family of the font: 
DEFAULT_PITCH 
The default pitch. 
FIXED_PITCH 
Fixed pitch. 
VARIABLE PITCH 
Variable pitch. 
FF_DECORATIVE 
Showy, decorative font face. 
FF_DONTCARE 
Do not care about the font face. 
FF_MODERN 
Modern font face (monospaced, sans serif font). 
FF_ROMAN 
Roman font face (proportional-width, serif font). 
FF_SCRIPT 
Script font face which imitates script handwriting. 
FF_SWISS 
Swiss font face (proportional-width, sans serif font). 
IpszFace 
The name of the font face to use. 


Constant Definitions 
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Const FW_DONTCARE = 0 
Const FW_THIN = 100 
Const FW_EXTRALIGHT = 200 

Const FW_ULTRALIGHT = 200 

Const FW_LIGHT = 300 

Const FW_NORMAL = 400 

Const FW_REGULAR = 400 

Const FW_MEDIUM = 500 

Const FW_SEMIBOLD = 600 

Const FW_DEMIBOLD = 600 

Const FW_BOLD = 700 

Const FW_EXTRABOLD = 800 

Const FW_ULTRABOLD = 800 

Const FW_HEAVY = 900 

Const FW_BLACK = 900 

Const ANSI_CHARSET = 0 

Const ARABIC_CHARSET = 178 
Const BALTIC_CHARSET 186 
Const CHINESEBIG5S_CHARSET = 136 
Const DEFAULT_CHARSET = 1 

Const BASTEUROPE_CHARSET = 238 
Const GB2312_CHARSET = 134 
Const GREEK _CHARSET = 161 
Const HANGEUL_CHARSET = 129 
Const HEBREW CHARSET = 177 
Const JOHAB CHARSET = 130 
Const MAC_CHARSET JA 

Const OEM_ CHARSET 255 
Const RUSSIAN_ CHARSET = 204 
Const SHIFTJIS_CHARSET = 128 
Const SYMBOL_CHARSET = 
Const THAI_CHARSET = 22 






























































2 
2 









































Const TURKISH _CHARSET = 162 
Const OUT_DEFAULT_PRECIS = 0 
Const OUT_DEVICE_PRECIS = 5 
Const OUT_OUTLINE_PRECIS = 8 
Const OUT_RASTER_PRECIS = 6 
Const OUT_STRING_PRECIS = 1 
Const OUT_STROKE_PRECIS 3 
Const OUT_TT_ONLY _PRECIS = 7 
Const OUT_TT_PRECIS = 4 
Const CLIP DEFAULT _PRECIS = 0 
Const CLIP _EMBEDDED = 128 
Const CLIP_LH ANGLES = 16 





Const CLIP_STROKE_PRECIS = 2 
Const ANTIALIASED_ QUALITY = 4 
Const DEFAULT_QUALITY = 0 
Const DRAFT_QUALITY = 
Const NONANTIALIASED QUALITY = 3 
Const PROOF_QUALITY = 2 
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Const DEFAULT_PITCH = 0 
Const FIXED PITCH = 1 
Const VARIABLE PITCH = 2 
Const FF_DECORATIVE = 80 
Const FF_DONTCARE = 0 
Const FF_ROMAN = 16 
Const FF_SCRIPT = 64 
Const FF_SWISS = 32 











Example 


' This code is licensed according to the terms and conditions listed here. 





' Draw the alphabet in the upper-left corner of window Forml using 
' the goofy Symbol font. 





Dim hFont As Long ' handle to the Symbol font which is created 
Dim hOldFont As Long ' handle to the font previously selected by Forml 
Dim retval As Long ' return value 











' Create a font object using the Symbol font. Only apply boldface 

' formatting to the font -- use defaults for most other settings. 

hFont = CreateFont(0, 0, 0, 0, FW BOLD, 0, 0, 0, SYMBOL _CHARSET, OUT_DEFAULT_PRECIS, 
CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, DEFAULT_PITCH Or FF_DECORATIVE, "Symbol") 




















' Select that font for use with Forml, saving the previous selection. 
hOldFont = SelectObject (Forml.hnDC, hFont) 

' Draw the alphabet near the upper-left corner. 

retval = TextOut (Forml.hDC, 10, 10, "“ABCDEFGHIJKLMNOPQRSTUVWXYZ", 26) 









































' Select the previous font back. 

retval = SelectObject (Forml.hDC, hOldFont) 

' Delete the font we created to free up resources. 
retval = DeleteObject (hFont) 

See Also 

CreateFontIndirect 


Category 
Fonts & Text 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: October 13, 1999 
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CreateFontindirect Function 


Declare Function CreateFontIndirect Lib "gdi32.d1l" Alias 
"CreateFontIndirectA" (lplf As LOGFONT) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreateFontIndirect creates a font object, which allows a font with given attributes to be used to draw text on a 
device. The font created by the function is the one which most closely matches the attributes of the logical font 


information passed via the structure. After your program is finished using the font, it must be deleted by using 
DeleteObject. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a handle to the font just created. 


Visual Basic-Specific Issues 
None. 
Parameters 


Iplf 
Information describing the desired attributes to give to the newly created font. 


Example 
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This code is licensed according to the terms and conditions listed here. 











' Use the font used by Windows to draw the title text of 

' icons to write the alphabet on window Forml. 

Dim lf As LOGFONT ' receives information about the font Windows uses 

Dim hFont As Long ' handle to the font that is created 

Dim hOldFont As Long ' handle to the font which Forml previously had selected 
Dim retval As Long ' return value 


iJ 











Get the attributes of the logical font used by Windows to 
draw the title text of icons. 


Li, 0) 








retval = SystemParametersInfo(SPI_GETICONTITLELOGFONT, Len(lf), 


iJ 


hFont = CreateFontIndirect (1f) 





Create a font matching the logical font description. 


Select that font for use in Forml, noting the previous font. 





hOldFont = SelectOb ject (Forml.hDC, hFont) 








Write the alphabet near the upper-left corner of Forml. 


retval = TextOut (Forml.hDC, 10, 10, “ABCDEFGHIJKLMNOPORSTUVWXYZ" 


T 


Restore the previously selected font for use in Forml. 


retval = SelectObject (Forml.hnDC, hOldFont) 


T 





Delete the created font to free resources. 











retval = DeleteObject (hFont) 





See Also 


CreateFont 


Category 


Fonts & Text 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


Last Modified: October 11, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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This page is at http://www. vbapi.com/ref/c/createfontindirect.html 
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CreateHatchBrush Function 


Declare Function CreateHatchBrush Lib "gdi32.d1ll" (ByVal nIndex As Long, ByVal 
crColor As Long) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


CreateHatchBrush creates a hatched brush object. When used to fill an area or shape, this brush produces a pattern of lines 
(a "hatch pattern") in a single color using an 8x8 unit cell. After the program finishes using the hatched brush, it should use 
DeleteObject to delete the brush and free system resources. The function returns a handle to the newly created hatched brush 
if successful, or O if an error occured. 


nIndex 
Exactly one of the following flags specifying which hatch pattern to use to make the brush: 
HS_BDIAGONAL = 3 
Diagonal lines from the bottom-left to the upper-right. 
HS_CROSS =4 
Cross pattern of horizontal and vertical lines. 
HS_DIAGCROSS = 5 
Cross pattern of perpendicular diagonal lines. 
HS_FDIAGONAL = 2 
Diagonal lines from the upper-left to the bottom-right. 
HS_HORIZONTAL = 0 
Horizontal lines. 
HS_VERTICAL = 1 
Vertical lines. 
crColor 
The RGB value of the color to give the hatched brush. Visual Basic users can use the RGB() function to generate this 
value. 


Example: 


Draw a rectangle with corners (10,20) and (175,100) 




















' on window Forml. Use a yellow brush with a diagonal cross pattern to fill the 
rectangle. 

Dim hbrush As Long ' receives handle to the hatched yellow brush 

Dim holdbrush As Long ' receives handle to Formli's default brush 

Dim retval As Long ' return value 

hbrush = CreateHatchBrush (HS_DIAGCROSS, RGB(255, 255, 0)) " create a hatched yellow 
brush 

' Save Forml's default brush so we can restore it after the program is finished 
holdbrush = SelectObject (Forml.hDC, hbrush) " select the brush 








Draw the rectangle filled using the hatched yellow brush 
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retval = Rectangle(Forml.hDC, 10, 20, 175, 100) 


E 





' Restore Forml's previous brush before destroying the created on 
retval = SelectObject (Form1.hDC, holdbrush) ' select old brush 
retval = DeleteObject (hbrush) ' destroy the hatched yellow brush 





























See Also: CreateSolidBrush 
Category: Brushes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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CreatePen Function 


Declare Function CreatePen Lib "gdi32.d1ll1" (ByVal fnPenStyle As Long, ByVal 
nWidth As Long, ByVal crColor As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


CreatePen creates a pen object. The shape of the pen created by the function is always a square having a side 
length equal to nWidth. After your program is finished using the pen, it must be deleted via the DeleteObject 
function. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a handle to the newly created pen. 





Visual Basic-Specific Issues 


None. 


Parameters 


jnPenStyle 
One of the following flags specifying the style of the pen to create: 
PS_SOLID 
The pen is solid. 
PS_DASH 
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The pen is dashed. nWidth must be less than or equal to one. 
PS_DOT 
The pen is dotted. nWidth must be less than or equal to one. 
PS_DASHDOT 
The pen has alternating dashes and dots. nWidth must be less than or equal to one. 
PS_DASHDOTDOT 
The pen has alternating dashes followed by two dots. nWidth must be less than or equal to one. 
PS_NULL 
The pen is invisible. 
PS_INSIDEFRAME 
The pen is solid. Whenever a drawing function draws a figure inside a bounding rectangle, the 
dimensions of the figure are shrunk so that the entire figure, including the width of the pen, fits 
entirely within the bounding rectangle. 
nWidth 
The width of the pen. If this is 0, the pen is always exactly one pixel wide no matter what. 
crColor 
The RGB value of the color to give the pen. 


Constant Definitions 


Const PS SOLID = 0 

Const PS_DASH = 1 

Const PS_DOT = 2 

Const PS _DASHDOT = 3 
Const PS_DASHDOTDOT = 4 
Const PS NULL = 5 

Const PS_INSIDEFRAME = 6 




















Example 


' This code is licensed according to the terms and conditions listed here. 





' Draw an ellipse on window Forml using a one-pixel-wide 
" square dashed green pen. 








Dim hPen As Long ' handle to the pen created 
Dim hOldPen As Long ' handle to Forml's previously selected pen 
Dim retval As Long ' return value 


' Create the square dashed green pen with a width of zero (always one pixel). 
hPen = CreatePen(PS_ DASH, 0, RGB(0O, 255, 0O)) 
' Select the pen for use by window Forml. 
hOldPen = SelectObject (Forml.hDC, hPen) 











' Draw an ellipse with bounding rectangle (100,150)-(350,300). 
retval = Ellipse(Forml.hDC, 100, 150, 350, 300) 
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' Select the old pen for use by Forml. 

retval = SelectObject (Forml.hDC, hOldPen) 

' Delete the pen we created to free up resources. 
retval = DeleteObject (hPen) 

See Also 

CreatePenIndirect 





Category 


Pens 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: October 16, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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CreatePenIindirect Function 





Declare Function CreatePenIndirect Lib "gdi32.d11" (lpLogPen As LOGPEN) As 
Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreatePenIndirect creates a pen object. The pen created is the one which is described by the logical pen 
information in the structure passed to the function. After your program is finished using the pen, it should be 
deleted via the DeleteObject function. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a handle to the newly created pen. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpLogPen 
The description of the attributes to give to the newly created pen. 


Example 
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' This code is licensed according to the terms and conditions listed here. 














' Draw an ellipse on window Forml using a one-pixel-wide 

" square dashed green pen. 

Dim hPen As Long ' handle to the pen created 

Dim hOldPen As Long ' handle to Forml's previously selected pen 
Dim lpinfo As LOGPEN ' holds description of the pen 

Dim retval As Long ' return value 





' Create the square dashed green pen with a width of zero (always one pixel). 

















lpinfo.lopnStyle = PS_DASH ' dashed line 
lpinfo.lopnWidth.x = 0 ' minimum width 
lpinfo.lopnWidth.y = 0 ' this member is ignored 
lpinfo.lopnColor = RGB(0, 255, 0) ' green 





hPen = CreatePenIndirect (lpinfo) 
' Select the pen for use by window Forml. 
hOldPen = SelectObject (Forml.hDC, hPen) 








' Draw an ellipse with bounding rectangle (100,150)-(350,300). 
retval = Ellipse(Forml.hDC, 100, 150, 350, 300) 








' Select the old pen for use by Forml. 

retval = SelectObject (Forml.hDC, hOldPen) 

' Delete the pen we created to free up resources. 
retval = DeleteObject (hPen) 























See Also 


CreatePen 


Category 


Pens 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: October 16, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


http://216.26.168.92/vbapi/ref/c/createpenindirect.html (2 of 3) [9/1/2002 5:12:59 PM] 


Windows API Guide: CreatePenIndirect Function 


This page is at http://www.vbapi.com/ref/c/createpenindirect.html 


http://216.26.168.92/vbapi/ref/c/createpenindirect.html (3 of 3) [9/1/2002 5:12:59 PM] 


Windows API Guide: CreatePolygonRgn Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





CreatePolygonRgn Function 








Declare Function CreatePolygonRgn Lib "gdi32.d11" (lpPoint As POINT TYPE, ByVal 
nCount As Long, ByVal nPolyFillMode As Long) As Long 














` 








Platforms: Win 32s, Win 95/98, Win NT 


CreatePolygonRgn creates a polygonal region and provides a handle to it. The polygon is defined by an array of points 
specifying its vertices. Note that the polygon fill mode must explictly be specified, instead of using the one set for whatever 
device the region is used with. The function returns the handle to the newly created region if successful, or 0 if an error 
occured. 


[pPoint 

An array holding the vertices of the polygonal region. Specify each point in order only once. 
nCount 

The number of elements in the array passed as /pPoint. 
nPolyFillMode 


Exactly one of the following flags specifying the polygon fill mode to use for the polygonal region: 
ALTERNATE = 1 


Alternates between filling and not filling contiguous sections whose boundaries are determined by the edge(s) of 
the polygon crossing through the polygon’s interior. 
WINDING = 2 


Any section inside the polygon is filled, regardless of any intra-polygonal boundaries and edges. 


Example: 





Invert the pixels within a triangular region on window Forml. The triangular 

' region has vertices (150,150), (250, 200), and (100, 200). Note how the points are 
loaded 

' into the array of vertices. 


























Dim vertex(0 To 2) As POINT TYPE ' array of region's vertices 
Dim hrgn As Long ' handle to the triangular region 
Dim retval As Long ' return value 





Load the vertices of the triangular region into the array. 











vertex(0).x = 150: vertex(0).y = 150 ' Ist point: (150,150) 
vertex(1).x = 250: vertex(1).y = 200 ' 2nd point: (250,200) 
vertex(2).x = 100: vertex(2).y = 200 ' 3rd point: (100,200) 





' Create the polygonal region based on the array of vertices. 
hrgn = CreatePolygonRgn (vertex(0), 3, ALTERNATE) ' for a triangle, fill mode is 
irrelevant 

















' Invert the pixels within the triangular region on Forml. 
retval = InvertRgn(Forml.hDC, hrgn) 




















' Delete the region to free up resources. 
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retval = DeleteObject (hrgn) 








See Also: CreatePolyPolygonRgn 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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CreatePolyPolygonRgn Function 


Declare Function CreatePolyPolygonRgn Lib "gdi32.d11" (lpPoint As POINT TYPE, 
lpPolyCounts As Long, ByVal nCount As Long, ByVal nPolyFillMode As Long) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


CreatePolyPolygonRgn creates a region consisting of multiple polygons. The vertices of all the polygons are passed to the 
function in the array passed as /pPoint. Another array specifies how many points within that array belong to each polygon. 
The individual polygons are not joined in any way, forming a region of multiple unconnected polygonal areas. Note that the 
fill mode for the multi-polygonal region must be specified explicitly, instead of using the filling mode set for whatever device 
the region is used on. The function returns the handle to the newly created region if successful, or 0 if an error occured. 


[pPoint 
An array holding the vertices of every polygon making up the new region. Specify each point for each polygon only 
once. See the example for a demonstration of how to load multiple polygons into this array. 
IpPolyCounts 
An array specifying how many vertices in the array passed as /pPoint belong to each polygon. 
nCount 
The number of elements in the array passed as /pPolyCounts. 
nPolyFillMode 
Exactly one of the following flags specifying the fill mode used for each polygon within the region: 
ALTERNATE = 1 
Alternates between filling and not filling contiguous sections whose boundaries are determined by the edge(s) 
of the polygon crossing through the polygon's interior. 
WINDING = 2 
Any section inside the polygon is filled, regardless of any intra-polygonal boundaries and edges. 


Example: 


' Invert the points lying within a multi-polygonal region on window Formi. The 
' region is made up of a triangle and a diamond. The triangle has vertices (25,25), 
(50,50), 














' and (25,50). The diamond has vertices (150,150), (200,200), (150,250), and 
(100,200). 

Dim vertex(0 To 6) As POINT TYPE ' holds vertices of each polygon 

Dim numvertices(0 To 1) As Long ' holds how many vertices belong to each polygon 
Dim hrgn As Long ' handle to the multi-polygonal region 

Dim retval As Long ' return value 








' Load the vertices of the triangle into the vertex array. 
vertex (0).x = 25: vertex(0).y = 25 ' Ist point: (25,25) 
vertex(1).x = 50: vertex(1).y = 50 ' 2nd point: (50,50) 
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vertex (2).x = 25: vertex(2).y = 50 ' 3rd point: (25,50) 
numvertices(0) = 3 ' three vertices for the triangle 


' Load the vertices of the diamond into the vertex array. 








vertex (3).x = 150: vertex(3).y = 150 ' Ist point: (150,150) 
vertex (4) .x = 200: vertex(4).y = 200 ' 2nd point: (200,200) 
vertex (5).x = 150: vertex(5).y = 250 ' 3rd point: (150,250) 
vertex (6).x = 100: vertex(6).y = 200 ' 4th point: (100,200) 
numvertices(1l) = 4 ' four vertices for the triangle 








' Create the multi-polygonal region and get a handle to it. 

hrgn = CreatePolyPolygonRgn (vertex(0), numvertices(0), 2, ALTERNATE) 
' Invert the pixels within this region on Forml. 

retval = InvertRgn(Forml.hDC, hrgn) 














" Delete the region to free up resources. 
retval = DeleteObject (hrgn) 














See Also: CreatePolygonRgn 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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CreatePopupMenu Function 
Declare Function CreatePopupMenu Lib "user32.d1l1" () As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreatePopupMenu creates a new popup menu object. This menu can then be used for a submenu or a popup menu such as a 
context menu. The new popup menu is initially empty; use InsertMenultem to fill it with the desired menu items. When your 





program no longer needs the popup menu, it should destroy it as necessary using DestroyMenu. 


Return Value 


If successful, the function returns a handle to the newly created popup menu. If an error occured, the function returns 0 (use 





GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function CreatePopupMenu Lib "user32.dl1" () As Long 


Public Declare Function DestroyMenu Lib "user32.dll1" (ByVal hMenu As Long) As Long 




















http://216.26.168.92/vbapi/ref/c/createpopupmenu.html (1 of 5) [9/1/2002 5:13:15 PM] 


Windows API Guide: CreatePopupMenu Function 

















Public Type MENUITEMINFO 
cbSize As Long 

fMask As Long 

fType As Long 

fState As Long 

wID As Long 

hSubMenu As Long 

hbmpChecked As Long 

hbmpUnchecked As Long 

dwiItemData As Long 

dwTypeData As String 

cch As Long 























End Type 

























































































ByVal 





hMenu As Long, ByVal ulItem As Long, 





MENUITEMINFO) As Long 
Public Type RECT 




















left As Long 
top As Long 
right As Long 
bottom As Long 
End Type 
Public Type TPMPARAMS 
cbSize As Long 
rcExclude As RECT 

















End Type 





Public Declare Function TrackPopupMenul 

















Ex Lib "user32.d11" 














fuFlags As Long, ByVal x As Long, ByVal y As Long, 






























































As 

TPMPARAMS) As Long 
Public Const TPM_LEFTALIGN = &HO 
Public Const TPM_TOPALIGN = &HO 
Public Const TPM_NONOTIFY = &H80 
Public Const TPM _RETURNCMD = &H100 
Public Const TPM_LEFTBUTTON = &HO 
Public Type POINT TYPE 

x As Long 

y As Long 
End Type 


Public Const MIIM_STATE = &H1 

Public Const MIIM_ID = &H2 

Public Const MIIM_TYPE = &H10 

Public Const MFT_SEPARATOR = &H800 

Public Const MFT STRING = &HO 

Public Const MFS DEFAULT = &H1000 

Public Const MFS ENABLED = &HO 

Public Declare Function InsertMenultem Lib "user32.d1ll1" Alias "InsertMenuItemA" 
( 





(ByVal hMenu As Long, 





ByVal hWnd As Long, 





ByVal fByPosition As Long, lpmii As _ 





ByVal 


lptpm 


Public Declare Function GetCursorPos Lib "user32.d11" (lpPoint As POINT TYPE) As Long 














Public Declare Function SetRe 








D 





ctEmpty Lib "user32.dll" (lpRect As RECT) As Long 
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' When the user clicks button Commandl, have a very simple popup menu appear. The 
' menu only has two options, divided by a separator bar. The menu is created when 
" needed and is destroyed after its use. 
' The following application-defined constants are used to name the menu item 
' identifiers used by this example. They are not actually part of the API; instead, 
they are 
' used just to eliminate "magic numbers." 
Private Const ID_ABOUT = 101 
Private Const ID_SEPARATOR = 102 
Private Const ID_EXIT = 103 
Private Sub Commandl1_Click () 
Dim hPopupMenu As Long ' handle to the popup menu to display 
Dim mii As MENUITEMINFO ' describes menu items to add 
Dim tpm As TPMPARAMS ' identifies the exclusion rectangle 
Dim curpos As POINT TYPE ' holds the current mouse coordinates 
Dim menusel As Long ' ID of what the user selected in the popup menu 
Dim retval As Long ' generic return value 
' Create the popup menu that will be displayed. 
hPopupMenu = CreatePopupMenu () 
' Add the menu's first item: "About This Problem..." 
With mii 
' The size of this structure. 
.cbSize = Len (mii) 
' Which elements of the structure to use. 
.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' The type of item: a string. 
.fType = MFT_STRING 
' This item is currently enabled and is the default item. 
-£fState = MFS_ ENABLED Or MEFS DEFAULT 
' Assign this item an item identifier. 
.wID = ID_ABOUT 
' Display the following text for the item. 
.dwTypeData = "&About This Example..." 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 0, 1, mii) 
" Add the second item: a separator bar. 
With mii 
.fType = MFT_SEPARATOR 
.fState = MFS_ENABLED 
.wID = ID_SEPARATOR 
End With 
retval = InsertMenulItem(hPopupMenu, 1, 1, mii) 
' Add the final item: "Exit". 
With mii 
.fType= MFT_STRING 
-wID = ID_EXIT 
.dwTypeData = "Eéxit" 
.cch = Len(.dwTypeData) 
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End With 
retval = InsertMenulItem(hPopupMenu, 2, 1, mii) 











" Determine where the mouse cursor currently is, in order to 
' the popup menu appear at that point. 
retval = GetCursorPos (curpos) 

















' Make the exclusion rectangle empty because there's no need 
With tpm 

' Size of the structure. 

.cbSize = Len (tpm) 

' Make the exclusion rectangle empty. 

retval = SetRectEmpty (.rcExclude) 
End With 






































' Display the popup menu at the mouse cursor. Instead of 
' to window Forml, have the function merely return the ID of 
selection. 








have 





for it here. 


sending messages 
the user's 








menusel = TrackPopupMenuEx (hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or 











TPM_NONOTIFY _ 













































































Or TPM_RETURNCMD Or TPM_LEFTBUTTON, curpos.x, curpos.y, Forml.hWnd, 
tpm) 
' Before acting upon the user's selection, destroy the popup menu now. 
retval = DestroyMenu (hPopupMenu) 
Select Case menusel 
Case ID_ABOUT 
' Use the Visual Basic MsgBox function to display a short message in 
a dialog 
' box. Using the MessageBox API function isn't necessary. 
retval = MsgBox("This example demonstrates how to use the API to 
display " & _ 
"a pop-up menu.", vbOkOnly Or vbInformation, "Windows API 
Guide") 
Case ID_EXIT 
' End this program by closing and unloading Forml. 
Unload Forml 
End Select 
End Sub 





See Also 


DestroyMenu 


Category 


Menus 


Back to the Function list. 
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Back to the Reference section. 
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Go back to the Windows API Guide home page. 
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CreateRectRgn Function 


Declare Function CreateRectRgn Lib "gdi32.d1ll1" (ByVal X1 As Long, ByVal Y1 
As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


CreateRectRgn creates a rectangularly-shaped region and provides a handle to it. The rectangle defining the 
region is specified by passing its upper-left and lower-right corners to the function. Note that the bottom and right 
edges of the rectangle are not considered to be part of the region. The function returns a handle to the newly 
created region if successful, or 0 if an error occured. 


” The x-coordinate of the upper-left corner of the rectangle. 
" The y-coordinate of the upper-left corner of the rectangle. 
x The x-coordinate of the lower-right corner of the rectangle. 
Á The y-coordinate of the lower-right corner of the rectangle. 


Example: 


' Invert the pixels within a rectangular region on window Forml. The region 
' has corners (20,30)-(150,110). 
Dim hrgn As Long ' handle to the rectangular region 


Dim retval As Long ' return value 





Create the rectangular region and get a handle to it. 

hrgn = CreateRectRgn (20, 30, 150, 110) ' has corners (20,30)-(150,110) 
' Invert the pixels on Forml within this region. 

retval = InvertRgn(Forml.hDC, hrgn) 





Delete the region to free up resources. 
retval = DeleteObject (hrgn) 








See Also: CreateRectRgnIndirect, CreateRoundRectRgn 
Category: Regions 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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CreateRectRgnindirect Function 


Declare Function CreateRectRgnindirect Lib "gdi32.d11" (lpRect As RECT) As 
Long 


Platforms: Win 32s, Win 95/98, Win NT 

CreateRectRgnIndirect creates a rectangularly-shaped region and provides a handle to it. The rectangle 
defining the region is specified by the rectangle passed to the function. Note that the bottom and right edges of 
the rectangle are not considered to be part of the region. The function returns a handle to the newly created 


region if successful, or 0 if an error occured. 


lpRect 
The rectangle which defines the rectangular region to create. 


Example: 


' Invert the pixels within a rectangular region on window Forml. The region 
' has corners (20,30)-(150,110). 


Dim therect As RECT ' rectangle used to create region 
Dim hrgn As Long ' handle to the rectangular region 
Dim retval As Long ' return value 


' Set the rectangle to use to create the region. 

retval = SetRect (therect, 20, 30, 150, 110) " therect = (20,30)-(150,110) 
" Create the rectangular region based on this rectangle. 

hrgn = CreateRectRgnIndirect (therect) 

' Invert the pixels within this region on Forml. 

retval = InvertRgn(Forml.hDC, hrgn) 








" Delete the region to free up resources. 
retval = DeleteObject (hrgn) 











See Also: CreateRectRgn, CreateRoundRectRgn 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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CreateSolidBrush Function 


Declare Function CreateSolidBrush Lib "gdi32.dl1l" (ByVal crColor As Long) As 
Long 





Platforms: Win 32s, Win 95/98, Win NT 
CreateSolidBrush creates a solid brush object. When used to fill an area or shape, this brush creates a solid fill of a 
single color. After it is finished using the brush, the program should use DeleteObject to delete the brush and free up 


system resources. The function returns a handle to the newly created solid brush if successful, or 0 if an error occured. 


crColor 
The RGB value of the color to give the solid brush. Visual Basic users can use the intrinsic RGB() function to 
calculate this value. 


Example: 


' Draw a rectangle with corners (10,20) and (175,100) 


' on window Forml. Use a solid yellow brush to fill the rectangle. 

Dim hbrush As Long ' receives handle to the solid yellow brush 

Dim holdbrush As Long ' receives handle to Forml's default brush 

Dim retval As Long ' return value 

hbrush = CreateSolidBrush(RGB(255, 255, 0)) ' create a solid yellow brush 

' Save Forml's default brush so we can restore it after the program is finished 
holdbrush = SelectObject (Forml.hDC, hbrush) ' select the brush 





' Draw the rectangle filled using the solid yellow brush 
retval = Rectangle (Forml.hDC, 10, 20, 175, 100) 


" Restore Forml's previous brush before destroying the created one 
retval = SelectObject (Forml.hDC, holdbrush) " select old brush 


retval = DeleteObject (hbrush) ' destroy the solid yellow brush 








See Also: CreateHatchBrush 
Category: Brushes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Create Toolhelp32Snapshot Function 





Declare Function CreateToolhelp32Snapshot Lib "kernel32.d11" (ByVal dwFlags As Long, 
ByVal th32ProcessID As Long) As Long 














Platforms 


Windows 95: Supported. 
Windows 98: Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Description & Usage 


CreateToolhelp32Snapshot creates a snapshot of what is running on the computer the moment the function is called. 
Depending on the flags specified, this snapshot can include running processes and/or threads, among other things. With this 
snapshot, you can then examine what things were running when the snapshot was made. After your program no longer needs 
the snapshot, destroy it using CloseHandle. 


Return Value 


If successful, the function returns a handle to the snapshot that was made. If an error occured, the functions returns -1 (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


dwFlags 

A combination of the following flags specifying which information to include in the snapshot: 
TH32CS_INHERIT 

Make the returned snapshot handle inheritable. 
TH32CS_SNAPALL 

Include everything (heap list of a process, modules, processes, and threads) in the snapshot. 
TH32CS_SNAPHEAPLIST 

Include the heap list of the process specified by th32ProcessID in the snapshot. 
TH32CS_SNAPMODULE 
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Include the module list of the process specified by th32ProcessID in the snapshot. 
TH32CS_SNAPPROCESS 
Include the process list in the snapshot. 
TH32CS_SNAPTHREAD 
Include the thread list in the snapshot. 
th32ProcessID 
The identifier of the process for when TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE is specified in 
dwFlags. A value of 0 indicates the current process. If neither of those two flags are specified, this parameter is ignored. 


Constant Definitions 





































































































Const TH32CS_INHERIT = &H80000000 
Const TH32CS_SNAPALL = &HF 

Const TH32CS_SNAPHEAPLIST = &H1 
Const TH32CS_SNAPPROCESS = &H2 
Const TH32CS_SNAPTHREAD = &H4 
Const TH32CS_SNAPMODULE = &H8 
Example 


Print a list of all the processes currently running on the computer when the user clicks button Command1. To do this, a 
snapshot of the running process list is taken, and then each process in it is analyzed. The filename of the process and the 
number of threads owned by it is then displayed. To use this example, place a command button named Command! on a form 
window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function CreateToolhelp32Snapshot Lib "kernel32.dl1l" (ByVal dwFlags As 
Long, ByVal _ 
th32ProcessID As Long) As Long 
Public Const TH32CS_SNAPPROCESS = &H2 
Public Type PROCESSENTRY32 
dwSize As Long 
cntUsage As Long 
th32ProcessID As Long 
th32DefaultHeapID As Long 
th32ModuleID As Long 
cntThreads As Long 
th32ParentProcessID As Long 
pcPriClassBase As Long 
dwFlags As Long 
szExeFile As String * 260 
End Type 
Public Declare Function Process32First Lib "kernel32.d11" (ByVal hSnapshot As Long, 
lppe As PROCESSENTRY32) As Long 
Public Declare Function Process32Next Lib "kernel32.d11" (ByVal hSnapshot As Long, 
lppe As PROCESSENTRY32) As Long 
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Public Declare Function CloseHandle Lib "kernel32.d11" (ByVal hObject As Long) As 
Long 





' ***x Place the following code inside a form window. *** 


Private Sub Command1_Click () 












































Dim hSnapshot As Long ' handle to the snapshot of the process list 

Dim processInfo As PROCESSENTRY32 ' information about a process in that list 
Dim success As Long " success of having gotten info on another process 

Dim exeName As String ' filename of the process 

Dim retval As Long ' generic return value 

' First, make a snapshot of the current process list. 

hSnapshot = CreateToolhelp32Snapshot (TH32CS_SNAPPROCESS, 0) 





' Get information about the first process in the list. 
processInfo.dwSize = Len(processInfo) 
success = Process32First (hSnapshot, processInfo) 











' Make sure a handle was returned. 

If hSnapshot = -1 Then 

Debug.Print "Unable to take snapshot of process list!" 
Exit Sub 








End If 








' Loop for each process on the list. 
While success <> 0 


















































' Extract the filename of the process (i.e., remove th mpty space) 
xeName = Left (processInfo.szExeFile, InStr(processInfo.szExeFile, 
vbNullChar) - 1) 
' Display the process name and the number of threads it owns. 
Debug.Print "Process: "; exeName 
Debug.Print " - Number of threads:"; processInfo.cntThreads 
' Get information about the next process, if there is one. 
processInfo.dwSize = Len(processInfo) 
success = Process32Next (hSnapshot, processInfo) 
Wend 





' Destroy the snapshot, now that we no longer need it. 
retval = CloseHandle (hSnapshot) 
End Sub 








Category 


Tool Help 


Back to the Function list. 





Back to the Reference section. 





http://216.26.168.92/vbapi/ref/c/createtoolhelp32snapshot.html (3 of 4) [9/1/2002 5:13:42 PM] 


Windows API Guide: CreateToolhelp32Snapshot Function 


Last Modified: September 24, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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shop.com | 
CreateWindowEx Function 
Declare Function CreateWindowEx Lib "user32.dll" Alias "CreateWindowExA" (ByVal 


























dwExStyle As Long, ByVal lpClassName As String, ByVal lpWindowName As String, ByVal 
dwStyle As Long, ByVal x As Long, ByVal y As Long, ByVal nWidth As Long, ByVal 
nHeight As Long, ByVal hWndParent As Long, ByVal hMenu As Long, ByVal hInstance As 
Long, lpParam As Any) As Long 









































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


CreateWindowEx creates a new window. The window can be a "regular" (overlapped) window, a control on another window, 
or a popup window. 


Return Value 


If successful, the function returns a handle to the newly created window. If an error occured, the function returns zero (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


dwExStyle 
A combination of extended styles to give the window. 


lpClassName 
The name of the class to create the window using. This class must have previously been registered using 


RegisterClassEx, InitCommonControlsEx, or some other function that registers window classes. 





lpWindowName 
The name to give the newly created window. For controls, this text will be the initial content of the control. For regular 
windows, this text appears in the window's title bar. 
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dwStyle 
A combination of the window styles to give the window. This is normally a combination of base window styles and 
styles that are specific to the window's class. 


x 
The initial x-coordinate of the upper-left corner of the window to create. If this window is a child of another window, 
this coordinate is relative to its parent window, otherwise it is relative to the screen. If this is CW_USEDEFAULT (for 
an overlapped window only), y will be ignored and the window will be placed in a default position. 

x 


The initial y-coordinate of the upper-left corner of the window to create. It is interpreted in the same way as x. This 
parameter is ignored if x is set to CW_USEDEFAULT. 

nWidth 
The initial width of the window. If this is CW_USEDEFAULT (for overlapped windows only), nHeight will be ignored 
and the window will be given a default size. 

nHeight 
The initial height of the window. If x is set to CW_USEDEFAULT, this parameter will be ignored. 

hWndParent 
A handle to the parent of the window to create. If the window does not have a parent, this should be zero. Windows 
2000: Set this parameter to HWND_MESSAGE to create a message-only window. 

hMenu 
A handle to a menu to assign to the window. For child windows, this is the child-window identifier, used to notify its 
parent about events. To not give the window a menu, set this parameter to zero. 

hInstance 
A handle to the instance of the module or program that owns the window. 

lParam 
An additional value to associate with the window, used in the window creation messages. 


Constant Definitions 





Const CW_USEDEFAULT = &H80000000 
Const HWND_BROADCAST = &HFFFF 


























Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 


wVersion As Integer 











wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 

iMaxUdpDg As Long 
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lpVendorInfo As Long 





End Type 


Public 


Integer, 


Public 





Declare F 


lpWSADa 





Ga 


As WSADATA) 





Declare F 


As Long 








unction WSAStartup Lib "wsock32.d11" (ByVal wVersionRequested As 
unction WSACleanup Lib "wsock32.d1l1" () As Long 





Public Type HOST! 





Public 
Public 


As Long, 


Public 
As Any, 


Public 
As Any) 
Public 


As Any, 


ENT 


h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 





End Type 
Public Const AF_INET 
Declare Functio 





Declare Funct 
ByVal _ 





protocol 





Declare S 
source _ 


As Any, 


Declare F 


As Long 





Declare F 





ByVal _ 


lpString2 As Any) 


2 








htonl Lib 
tion gethostbyaddr Lib 


wsock32.dl1l1" (1 





"wsock32 





As Long) 


ByVal lengt 
Istrien Lib 


unction lsi 





As Long 
ub CopyMemory Lib "kernel32.d11" Alias 


th As Lon 








unc 


tion. lstrepy Lib 


As Long 


g) 
"kernel32.d11" 


Alias "lst 


ByVal hostlong As Long) 


-d11" (addr As Long, 


"RtlMoveMemory" ( 


trlenA" 








"kernel32.d11" 


Alias "lst 











Public Type INITCOMMONCONTROLSEX TY 
dwSize As Long 





dwICC As 
End Type 
Public 
Public Const ICC_INT 
Public 





~ 





Long, 


Public 
Public 
Public 
Public 


Public 


As Long, 


Public Const 
Public Const 





PE 











INITCOMMONCONTROLS! 


Long 


Declare Function InitCommonCon 





trolsEx Lib 











EX TYPE) 




















e 











As Long, 











Declare Fun 
ByVal Msg _ 





As Long, 


WC_ 
WS_CH 
WS_VIS 


IPM ISBLAN 





ERN 





ET CLASSES 








As Long, 





IPAD 
IL 





DRI 
D 
BLE 
tion 


ESS 




















Cc 


ByVal y As Long, 
hWndParent As Long, 
ByVal hMen 
Const 
Const 
Const 
Declare Fun 


u As Long, 


Declare Function CreateWindowEx Lib 
ByVal dwExSty] 
ByVal lpClassName As String, 
ByVal x _ 








H1000000 





As 
& 


Long 
H800 





"user32 


ALL” 


"“comctl32.dii™ 








ByVal nWidth As Long, 


ByVal hInstance As Long, 
"SysIPAddress32" 
&H40000000 
& 
Dest 


0 


troyWindow Lib "user32.d1l1" ( 








Alias 


ByVal 





trcpyA" 


(lp 


"Crea 


ByVal lpWindowName As String, 


lpParam As Any) 














ction 


SendMessage Lib 





wParam As 

















IPM GETADI 


K 
R 














ESS 


Any, 1Pa 


&H469 
&H466 





ram As Any) 
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"user32.d11" 


Alias 


As Long 


As 








(ByVal 


Long 


ByVal length 


Destination 


lpString 








(ByVal 





lpStringl 








teWindowl!l 





ByVal nHeight As Long, 


hWnd As Long) 
"SendMessageA" ( 


InitCtrls As _ 


EXA" 





ByVal dwStyle As 





ByVal 


As Long 


As Long 





ByVal hWnd 


Windows API Guide: CreateWindowEx Function 








' *** Place the following code in a form window. *** 





Private hIPControl As Long ' handle to the IP Address control 








' When the form is initialized, create an IP Address control in the 





' upper-left corner of the form. 
Private Sub Form_Initialize() 
Dim comctls As INITCOMMONCONTROLSEX TYPE 


























register 








Dim retval As Long 


identifies the control to 


' generic return value 


' Register the IP Address control window class. 





With comctls 
.dwSize = Len(comctls) 
.dwICC = ICC_INTERNET_ CLASSES 




















End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, 














O, 125, 20, 


wee 
r 








WS_CHILD 


Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





End Sub 








' Destroy the IP Address control when the form closes. 


Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 








retval = DestroyWindow (hIPControl) 
End Sub 

















Or WS_VISIBLE, 0, 





' Look up the primary domain name of the host computer identified by the 









































' address in the IP Address control. 

Private Sub cmdGetDomain_Click () 
Dim ipAddress_h As Long ' the IP address, in h 
Dim ipAddress_n As Long ' the IP address, in n 
Dim sockinfo As WSADATA ' information about th 
Dim pHostinfo As Long ' pointer to informati 
Dim hostinfo As HOSTENT ' information about th 
Dim domainName As String ' the primary domain n 
Dim retval As Long ' generic return value 

















' Verify that an IP address was entered. 








retval = SendMessage(hIPControl, IPM ISBLANK, 








If retval <> 0 Then 








Exit Sub 
End If 














Debug.Print "No IP address was entered!" 


ost byte order 


etwork byt 
e Winsock 


te order 
implementation 








on about 


the host computer 


e host computer 











ame of the host computer 





ByVal CLng(0), ByVal CLng(0) ) 


' Get the IP address entered by the user and verify that all 











' four fields in the address wer ntered 




















retval = SendMessage(hIPControl, IPM GETA 





D 


DR 








ESS, 














If retval < 4 Then 
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Debug.Print 
Exit Sub 





up a Winsock v2.2 session. 














End Ii 

' Open 

retval = WSAStartup (& 

f retval <> 0 Then 
Debug.Print 
Exit Sub 

End Ii 

" Convert the 


ipAddress_n = 














' Get information about the host computer. 
pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 
If pHostInfo = 0 Then 

Debug.Print 
Else 

Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, 

Copy the host domain name into a string. 
domainName = Space(lstrien(hostinfo.h_name) ) 
retval = lstrcpy(domainName, hostinfo.h_name) 
Debug.Print "Domain name is: "; domainName 

End Ii 
' End the Winsock session. 
retval = WSACleanup () 





End Sub 





See Also 


DestroyWindow 





Category 


Windows 


Back to the Function list. 


























H202, sockinfo) 

















Back to the Reference section. 





Last Modified: October 29, 2000 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 











Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 





This page is at http://www.vbapi.com/ref/c/createwindowex.html 





IP address into network byte order. 
htonl (ipAddress_h) 
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"An incomplete IP address was entered!" 


ERROR: Attempt to open Winsock failed: 





Len (hostini 


fo) 


error"; 


retval 


"Could not find a host with the specified IP address." 
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DefWindowProc Function 





Declare Function DefWindowProc Lib "user32.d1l1" Alias "DefWindowProcA" (ByVal hWnd 
As Long, ByVal Msg As Long, ByVal wParam As Long, ByVal lParam As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


DefWindowProc explicitly calls the operating system's default window procedure to process a message for a window. This 
default window procedure provides the minimal functionality necessary for a window procedure function and should be 
used to provide the default implementation of window messages. 


Return Value 


The function returns the return value of whatever message was processed. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 

A handle to the window to process a message for. 
Msg 

The message to process. 
wParam 

Additional information about the message. 
lParam 

Additional information about the message. 
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' This code is licensed according to the terms and conditions listed here. 


" Demonstrate how Visual Basic provides a more robust window 

' procedure for windows it creates for the programmer when compared 

" to Windows's default window procedure. Do this by "toggling" between 
" the default and the Visual Basic provided one. 














' *** Place the following code in a module. *** 
Public pVBProc As Long ' pointer to Visual Basic's window procedure 
' (The above variable defaults to 0 automatically.) 














' The following function acts as a wrapper. All it 
' does is call the default window procedure. 
Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 
Long, ByVal lParam As Long) As Long 
' Call the default window procedure and return its result. 
WindowProc = DefWindowProc (hWnd, uMsg, wParam, lParam) 
End Function 











' *** Place the following code wherever you wish. *** 
Dim retval As Long ' return value 








If pVBProc = 0 Then 
' Window Forml is using the VB-provided procedure. Switch to using 
' the default one and save the pointer to the VB one. 
PVBProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 
Else 
' Window Forml is using the default procedure (via the wrapper 
' function). Switch to using the VB one. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pVBProc) 
' Set pVBProc to 0 so we know which one is being used. 
PVBProc = 0 
End If 
' By allowing the user to switch back and forth, the differences will 
' become apparent. 




















See Also 


CallWindowProc 


Category 


Window Procedures 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








http://216.26.168.92/vbapi/ref/d/defwindowproc.html (2 of 3) [9/1/2002 5:14:00 PM] 


Windows API Guide: DefWindowProc Function 


Last Modified: August 23, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/d/defwindowproc.html 
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DeleteDC Function 

















Declare Function DeleteDC Lib "gdi32.d1l1" (ByVal hdc As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


DeleteDC destroys a device context which was created by CreateDC. Your program should delete a device context once it has 
finished using it in order to conserve resources. Do not use this function to close a device context gotten from GetDC -- for 
those, use ReleaseDC instead. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Information 


None. 


Parameters 


hdc 
A handle to the device context to delete. 


Example 


This code is licensed according to the terms and conditions listed here. 


' Print out 


pen on it. 


a page with an ellipse drawn with a thickened black 
The page is printed on the computer's default printer. 








ct ct 
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i 


declaratio 
tions to use pointe 
"kernel32 
lpString2 As Long) As Lo 
"kernel32 











The following are special 
manipulation func 
Declare Function lstrcpy Lib 
String, ByVal 
Declare Function lstrlen Lib 























As Long 


Variable declarations 














ns needed to allow string 
rs to strings. 

















-d1l1l" Alias “lstrcpyA" (ByVal lpStringl As 
ng 
-d1l1i" Alias "IstrlenA" (ByVal lpString As Long) 





































































































Dim hPrintDC As Long handle to the printer's device context 

Dim di As DOCINFO ' information about the document to print 

Dim hPen As Long ' handle to the pen to draw the ellipse with 

Dim hOldPen As Long ' handle to the printer's previously selected pen 

Dim buffer(0 To 3076 / 4) As Long ' 3076-byte buffer 

Dim pi2 As PRINTER INFO 2 ' receives info about the default printer 

Dim printret As Long ' receives the number of printers returned from EnumPrinters 
Dim spaceneeded As Long ' receives space requires for EnumPrinters 

Dim retval As Long ' return value 

' Get the device and driver names of the default printer. For a more detailed 

' description of the semi-confusing code below, consult the 

' EnumPrinters page. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 2, buffer(0), 3076, spaceneeded, 
printret) 


If 


retval 0 Then 
Debug.Print "No default printer is c 
End ' abort the program 
End If 




















onfigured." 





' Copy the device and driver names to 











the structure. All the 
eeded and is omitted here. 





























' other information retrieved is not n 
pi2.pPrinterName = Space (lstrlen (buffe 
retval = lstrcpy(pi2.pPrinterName, buf 
pi2.pDriverName = Space (lstrlen (buffer 
retval = lstrcpy(pi2.pDriverName, buff 




















Creat 
hPrintDC 





a device context to the print 
CreateDC("", pi2.pPrinterNa 
solid black brush with a th 


5, RGB(O, O0 








Create a 
hPen = CreatePen(PS_SOLID, 














Load information about the doc 
.cbSize Len (di) ' size of structu 


ument 





r(1))) 

fer(1)) 

(4))) 

er (4) ) 

er, uSing its default initialization. 
me, 0, ByVal CLng(0)) 





ickness of 5. 
, 0)) 

to print into the structure. 
re 














.lpszDocName = "Printer API Demonstr 
.lpszOutput 0. ' do not print toa 
.lpszDatatype = ' data type of f 


.fwType 0 no additional informa 











' 





i document 





ation" name of 
file 
ile doesn't apply 
tion 








Begin 
tval 


the print job. 
StartDoc(hPrintDC, di) 

Begin the first and only page to pri 
tval = StartPage (hPrintDC) 

Select the pen for use with the prin 








re 





























re 


k 





NE 


ter. 
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hoOldPen = SelectObject (nPrintDC, hPen) 










































































' Draw an ellipse with bounding rectangle corners (1000,1500)-(2000, 3000) 
retval = Ellipse(hPrintDC, 1000, 1500, 2000, 3000) 

' Restore the printer's previously selected pen. 

retval = SelectObject (hPrintDC, hOldPen) 

' End information about the first and only page. 

retval = EndPage(hPrintDC) 

' End information about the document. 

retval = EndDoc(hPrintDC) 


' The printer will now begin printing the document. 








' Delete the pen created for drawing. 
retval = DeleteObject (hPen) 

" Delete the device context to the printer. 
retval = DeleteDC (hPrintDC) 



































See Also 


CreateDC 


Category 


Devices 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: November 6, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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DeleteFile Function 


Declare Function DeleteFile Lib "kernel32.d11" Alias "DeleteFileA" 
(ByVal lpFileName As String) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


DeleteFile deletes a file completely -- it does not send it to the Recycle Bin. It also doesn't prompt to 
confirm the deletion, so use it carefully. The function returns 1 if successful, or 0 if an error occured 
(most likely the file doesn't exist). 


lp FileName 
The name of the file to delete. 


Example: 


' Delete the file C:\Dummy\therile,txt 
Dim retval As Long ' return value 





retval = DeleteFile("C:\Dummy\thefile.txt") 
If retval = 1 Then Debug.Print "File deleted successfully." 


Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/d/deletefile.html 


http://216.26.168.92/vbapi/ref/d/deletefile.html [9/1/2002 5:14:22 PM] 


Windows API Guide: DeleteObject Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





DeleteObject Function 


Declare Function DeleteObject Lib "gdi32.d1l1l" (ByVal hObject As Long) As Long 
DeleteObject deletes an object after the program has finished using it. These objects include bitmaps, brushes, fonts, 
palettes, pens, and regions. Of course the object should never be deleted until it is no longer in use by any devices (see 
the example for a demonstration). Deleting the object frees up system resources associated with it. The function 


returns 1 if successful, or 0 if an error occured. 


hObject 
A handle to the bitmap, brush, font, palette, pen, or region to delete. 


Example: 


' Draw a rectangle with corners (10,20) and (175,100) 





' on window Forml. Use a solid yellow brush to fill the rectangle. 

Dim hbrush As Long ' receives handle to the solid yellow brush 

Dim holdbrush As Long ' receives handle to Forml's default brush 

Dim retval As Long ' return value 

hbrush = CreateSolidBrush(RGB(255, 255, 0)) ' create a solid yellow brush 

' Save Forml's default brush so we can restore it after the program is finished 
holdbrush = SelectObject (Forml.hDC, hbrush) ' select the brush 





' Draw the rectangle filled using the solid yellow brush 

retval = Rectangle (Forml.hDC, 10, 20, 175, 100) 

" Restore Forml's previous brush before destroying the created one 
retval = SelectObject (Forml.hDC, holdbrush) " select old brush 
retval = DeleteObject (hbrush) ' destroy the solid yellow brush 





Category: Devices 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 





http://216.26.168.92/vbapi/ref/d/deleteobject.html (1 of 2) [9/1/2002 5:15:13 PM] 


Windows API Guide: DeleteObject Function 


This page is at http://www.vbapi.com/ref/d/deleteobject.html 


http://216.26.168.92/vbapi/ref/d/deleteobject.html (2 of 2) [9/1/2002 5:15:13 PM] 


Windows API Guide: DestroyCursor Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 














shop.com | 
DestroyCursor Function 
Declare Function DestroyCursor Lib "user32.dl11" (ByVal hCursor As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


DestroyCursor destroys a cursor and deletes its handle. The cursor must have been created using the CreateCursor 


functions. Do not use this function with a cursor handle obtained in any other manner! The function returns 1 if successful, 
or 0 if an error occured. 


hCursor 
A handle to the cursor to delete. 


Example: 


Create a 32x32 color cursor shaped somewhat like a yin-yang symbol. 

(The bit masks come from Microsoft's documentation on the API cursors function, 
just to 

' give them their due credit.) Note how the masks are loaded into the arrays. The 


new 
' 








cursor is then set to be the cursor for 10 seconds. 




















Dim hnewcursor As Long ' newly created cursor 

Dim holdcursor As Long ' receives handle of default cursor 

Dim andbuffer As String, xorbuffer As String ' buffers for masks 
Dim andbits(0 To 127) As Byte ' stores the AND mask 

Dim xorbits(0 To 127) As Byte ' stores the XOR mask 

Dim c As Integer, retval As Long ' counter and return value 





' Unfortunately, VB does not provide a nice way to load lots of information into an 
array. 

' To load the AND and XOR masks, we put the raw hex values into the string buffers 
' and use a loop to convert the hex values into numeric values and load them into 
the elements of the array. Yes, it's ugly, but there's no better way. Note the 
use of the line-continuation character here. Each sequence of eight hex 
characters represents one line in the 32x32 cursor. 



































andbuffer = "FFFC3FFF" & "FFCOILFFEF" & "FFOO3FFEF" & "FEOQOFFFF" & _ 
"FUOLFFFE" & “FOO3FFFF" & "“FOO3FFFF" & "“EOQOVFFFF" & _ 
"COO7FFFE" & “COOFFFFF" & "800FFFFF" & "800FFFFF" & _ 
"8007FFFF" & "8007FFFEF" & “OOO3FFFF" & "QOQOOFFFF" & _ 
"OOOO7FFE" & “OOOOLFFEF" & “OOQOQOQOFFEF" & "80000FFF" & _ 
"800007FF" & "800007FEF" & "COOOO7FEF" & "COOOOFFF" & _ 
"EFOOOOFFE" & "“FOOOLFFEF" & “"FOOOIFFEF" & "F8003FFF" & _ 
"FEOO7FFE" & “FFOOFFFEF" & "FFC3FFFF" & "“FFFFFFFE" 
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xorbuffer = "00000000" & "0003C000" & "OO3FO000" & "OOFEOOOO" & _ 
"OEFCO000" & "O7F80000" & "O7F80000" & "OFFOOOOO" & _ 
"IFF00000" & "1FE00000" & "3FE00000" & "3FE00000" & _ 
"3FF00000" & "7FF00000" & "7JFF80000" & "7FFC0000" & _ 
"7FFF0000" & "7FFF8000" & "7FFFEOOO" & "3FFFEOOO" & _ 
"3FC7FOO0" & "3F83F000" & "IF83F000" & "1F83E000" & _ 
"OFC7E000" & "O7FFCO000" & "O7FFCO0O00" & "O1FF8000" & _ 
"OQOFFOOOO" & "O003C0000" & "00000000" & "00000000" 
' Now load these hex values into the proper arrays. 
For c = 0 To 127 
andbits(c) = "&H" & Mid(andbuffer, 2 * c + 1) 
xorbits(c) = "&H" & Mid(xorbuffer, 2 * c + 1) 
Next c 
' Finally, create this cursor! The hotspot is at (19,2) on the cursor. 











hnewcursor = CreateCursor(App.hInstance, 19, 2, 32, 32, andbits(0), xorbits(0)) 
' Set the new cursor as the current cursor for 10 seconds and then switch back. 


holdcursor = SetCursor (hnewcursor) " change cursor 
Sleep 10000 ' wait for 10 seconds 
retval = SetCursor(holdcursor) " change cursor back 





' Destroy the new cursor. 
retval = DestroyCursor (hnewcursor) 





See Also: CreateCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/d/destroycursor.html 
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Destroylcon Function 


Declare Function DestroylIcon Lib "user32.d11" (ByVal hIcon As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


DestroyIcon destroys an icon and frees the memory which contained the icon. Some functions which provide an 
icon (sometimes but not necessarily creating it) require programs to use this function after using an icon, while 
others do not. Check the icon function in question to determine whether or not the icon must be destroyed. An icon 
cannot be in use when the program destroys it, whether it is used by the program or other programs. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns 
a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hIcon 
A handle to the icon to destroy. 


Example 
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' This code is licensed according to the terms and conditions listed here. 





' Display the first icon (index 0) stored in the executable file 
" C:\MyApp\Prog.exe on window Forml. The icon must be destroyed after the 
' program finishes using it. 

Dim hIcon As Long ' handle to the function gotten from the executable file 
Dim retval As Long ' return value 





' Extract the first icon stored in the aforementioned executable file. 
hIcon = ExtractIcon(App.hInstance, "C:\MyApp\Prog.exe", 0) 

' Only attempt to display the icon if we successfully extracted it. 

If hIcon = 0 Then 











Debug.Print "Failed to extract the icon -- aborting." 
End ' terminate the program 
Else 
' Display the icon at coordinates (100, 75) on window Forml. 
retval = Drawlcon(Forml.hDC, 100, 75, hIcon) 
' Although the icon's image is still visible, the icon itself is not in use. 














' Therefore we destroy it to free up resources. 
retval = DestroyIcon (hIcon) 
End If 


Category 


Icons 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


Last Modified: August 4, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/d/destroyicon.html 
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DestroyMenu Function 

Declare Function DestroyMenu Lib "user32.dl11" (ByVal hMenu As Long) As Long 
Platforms 

e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 

e Windows 2000: Supported. 

e Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


DestroyMenu destroys a menu resource. This menu can be either a "regular" menu (i.e., a menu bar) or a popup menu. Menus 
should be destroyed when no longer needed in order to free resources. However, it is not necessary to call DestroyMenu to 


destroy a menu that is assigned as a window's menu (or any submenus of that menu). Those menus are automatically destroyed 
when their window closes. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the menu to be destroyed. 


Example 


F 


This code is licensed according to the terms and conditions listed here. 


' 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
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Public Declare Function CreatePopupMenu Lib "user32.dl1" () As Long 














Public Declare Function DestroyMenu Lib "user32.dll1" (ByVal hMenu As Long) As Long 

Public Type MENUITEMINFO 
cbhSize As Long 

fMask As Long 

fType As Long 

fState As Long 

wID As Long 

hSubMenu As Long 

hbmpChecked As Long 

hbmpUnchecked As Long 

dwItemData As Long 

dwTypeData As String 

cch As Long 



































End Type 

Public Con 
Public Con 
Public Con 
Public Con 
P 
P 
P 
P 
( 





IIM_STATE = &H1 
IIM_ID = &H2 
IIM_TYPE = &H10 
FT_SEPARATOR = &H800 
ublic Con FT_STRING = &HO 
ublic Con FS DEFAULT = &H1000 
ublic Const MFS ENABLED = &HO 
ublic Declare Function InsertMenultem Lib "user32.dll" Alias "InsertMenuItemA" 
ByVal 























te ee ee 
ct 
Ss Ss Ss 3s SS 







































































hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As _ 
MENUITEMINFO) As Long 
Public Type RECT 


























left As Long 
top As Long 
right As Long 
bottom As Long 
End Type 
Public Type TPMPARAMS 
cbSize As Long 
rcExclude As RECT 

















End Type 
Public Declare Function TrackPopupMenuEx Lib "user32.d11" (ByVal hMenu As Long, ByVal 























fuFlags As Long, ByVal x As Long, ByVal y As Long, ByVal hWnd As Long, lptpm 






























































As 

TPMPARAMS) As Long 
Public Const TPM_LEFTALIGN = &H0O 
Public Const TPM_TOPALIGN = &HO 
Public Const TPM_NONOTIFY = &H80 
Public Const TPM _RETURNCMD = &H100 
Public Const TPM_LEFTBUTTON = &HO 
Public Type POINT TYPE 

x As Long 

y As Long 
End Type 








Public Declare Function GetCursorPos Lib "user32.d1l1" (lpPoint As POINT TYPI 





ey 
—_ 


As Long 
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Public Declare Function SetRectEmpty Lib "user32.d11" (lpRect As RECT) As Long 








' When the user clicks button Commandl, have a very simple popup menu appear. The 
' menu only has two options, divided by a separator bar. The menu is created when 
' needed and is destroyed after its use. 





' The following application-defined constants are used to name the menu item 

' identifiers used by this example. They are not actually part of the API; instead, 
they are 

' used just to eliminate "magic numbers." 

Private Const ID ABOUT = 101 

Private Const ID SEPARATOR = 102 

Private Const ID_EXIT = 103 




















Private Sub Command1_Click () 






































































































































































































































Dim hPopupMenu As Long ' handle to the popup menu to display 
Dim mii As MENUITEMINFO ' describes menu items to add 
Dim tpm As TPMPARAMS ' identifies the exclusion rectangle 
Dim curpos As POINT TYPE ' holds the current mouse coordinates 
Dim menusel As Long ' ID of what the user selected in the popup menu 
Dim retval As Long ' generic return value 
' Create the popup menu that will be displayed. 
hPopupMenu = CreatePopupMenu () 
' Add the menu's first item: "About This Problem..." 
With mii 
' The size of this structure. 
.cbSize = Len (mii) 
' Which elements of the structure to use. 
.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' The type of item: a string. 
.fType = MFT_STRING 
' This item is currently enabled and is the default item. 
-£fState = MFS_ENABLED Or MEFS DEFAULT 
' Assign this item an item identifier. 
.wID = ID_ABOUT 
' Display the following text for the item. 
-dwTypeData = "&About This Example..." 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 0, 1, mii) 
" Add the second item: a separator bar. 
With mii 
.f£Type = MFT_SEPARATOR 
.f£State = MFS_ENABLED 
.wID = ID_SEPARATOR 
End With 
retval = InsertMenulItem(hPopupMenu, 1, 1, mii) 
' Add the final item: "Exit". 
With mii 


.fType= MFT_STRING 
.wID = ID_EXIT 
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.dwTypeData = "E&éxit" 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 2, 1, mii) 














Determine where the mouse cursor currently is, in order to have 
' the popup menu appear at that point. 
retval = GetCursorPos (curpos) 








$ 





With tpm 
' Size of the structure. 
.cbSize = Len (tpm) 
' Make the exclusion rectangle empty. 
retval = SetRectEmpty (.rcExclude) 
End With 




















' 











Make the exclusion rectangle empty because there's no need for it here. 


Display the popup menu at the mouse cursor. Instead of sending messages 


' to window Forml, have the function merely return the ID of the user's 


selection. 

















menusel = TrackPopupMenuEx (hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or 





TPM_NONOTIFY _ 

















Or TPM_RETURNCMD Or TPM_LEFTBUTTON, curpos.x, curpos.y, Forml.hWnd, 























tpm) 
' Before acting upon the user's selection, destroy the popup menu now. 
retval = DestroyMenu (hPopupMenu) 
Select Case menusel 
Case ID_ABOUT 
' Use the Visual Basic MsgBox function to display a short message in 
a dialog 








' box. Using the MessageBox API function isn't necessary. 








retval = MsgBox("This example demonstrates how to use the API 


display " & 





to 


"a pop-up menu.", vbOkOnly Or vbInformation, "Windows API 


Guide") 
Case ID_EXIT 
' End this program by closing and unloading Forml. 
Unload Forml 
End Select 




















End Sub 





See Also 


CreatePopupMenu 





Category 


Menus 
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Back to the Function list. 





Back to the Reference section. 





Last Modified: June 4, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/d/destroymenu.html 
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EnableWindow Function 


Declare Function EnableWindow Lib "user32.d11" (ByVal hwnd As Long, 
ByVal fEnable As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


EnableWindow enables or disables a window. If a window is disabled, it cannot receive the focus and 
will ignore any attempted input. Some types of windows, such as buttons and other controls, will appear 
grayed when disabled, although any window can be enabled or disabled. The function returns 0 if the 
window had previously been enabled, or a non-zero value if the window had been disabled. 


hwnd 
A handle to the window to enable or disable. 
fEnable 
If 0, the window will be disabled. If non-zero, the window will be enabled. 








Example: 

" Reverse the enabled status of window Commandl. If the window is 

' disabled, enable it; if it is enabled, disable it. 

Dim wasenabled As Long ' receives enabled/disabled status of Commandl 
Dim retval As Long ' return value 


' Determine if the window Commandl is currently enabled or not. 
wasenabled = IsWindowEnabled(Command1.hWnd) 





If wasenabled = 0 Then ' if not enabled, enable it 
retval = EnableWindow (Commandl.hWnd, 1) 

Else ' if enabled, disable it 
retval = EnableWindow (Commandl.hWnd, 0) 

End If 


See Also: IsWindowEnabled 
Category: Windows 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/e/enablewindow.html 
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DestroyWindow Function 
Declare Function DestroyWindow Lib "user32.d1l1" (ByVal hWnd As Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Destroy Window destroys a window. Any menus, timers, or child windows are automatically destroyed along with it. 
Destroy Window only works with windows that are owned by the calling program, however. 


Return Value 


If successful, the function returns a nonzero value. If an error occured, the function returns zero (use GetLastError to get the 
error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to destroy. 


Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 
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' This code is licensed according to the terms and conditions 





' Declarations and such needed for the exampl 
(declaratio 


' (Copy them to the 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As 








In 








ns) 


teger 


szDescription As String * 257 
szSystemStatus As String * 129 





iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendorInfo As Long 
End Type 
Public Declare F 
Integer, lpWSAData 
As WSADATA) 
Declare F 











As Long 








Public 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 




















unction WSAStartup Lib "wsock32.d11" ( 


unction WSACleanup Lib "wsock32.d11" 


section of 





e: 
a module.) 








ByVal 





() As Long 





listed here. 


wVersionRequested As 


























End Type 
Public Const AF_INET = 2 
Public Declare Function htonl Lib "wsock32.dll" (ByVal hostlong As Long) As Long 
Public Declare Function gethostbyaddr Lib "wsock32.dll" (addr As Long, ByVal length 
As Long, ByVal _ 

protocol As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 

As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d1l1" Alias "l1strlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function Ilstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 


As Any, 


Public Type INITCOMMONCONTROLSEX TYPE 




















ByVal _ 


lpString2 As Any) As Long 

















dwSize As Long 
dwICC As Long 































































































End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INITCOMMONCONTROLSEX TYPE) As Long 
Public Const ICC_INTERNET_CLASSES = &H800 
Public Declare Function CreateWindowEx Lib "user32.d1ll" Alias "CreateWindowExA" 
(ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 





hWndParent As Long, 
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ByVal hMen 
Public Const WC_IP 


u As Long, ByVal hInstance As Long, lpParam As Any) As Long 
IPA 
Public Const WS_CHI 
S 
> 
C 


DDRESS = "SysIPAddress32" 

LD = &H40000000 

BLE = &H10000000 

tion DestroyWindow Lib "user32.dll" (ByVal hWnd As Long) As Long 

tion SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 

As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 

Public Const IPM ISBLANK = &H469 

Public Const IPM GETADDRESS = &H466 























Public Const WS_VI 
Public Declare Fun 
Public Declare Fun 






























































' ***x Place the following code in a form window. *** 
Private hIPControl As Long ' handle to the IP Address control 


' When the form is initialized, create an IP Address control in the 
' upper-left corner of the form. 
Private Sub Form_Initialize() 
Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 
































register 








Dim retval As Long ' generic return value 








' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_CLASSES 














End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 


O, 125, 20, 









































Me.hWnd, 0, App.hInstance, ByVal CLng(0) ) 























End Sub 
' Destroy the IP Address control when the form closes. It's not 
' really necessary to do this, since all children of the form will be automatically 
' destroyed once the form is destroyed. But this is just an example, after all. 
Private Sub Form_Unload(Cancel As Integer) 

Dim retval As Long ' return value 








retval = DestroyWindow (hIPControl) 
End Sub 





' Look up the primary domain name of the host computer identified by the 






























































' address in the IP Address control. 

Private Sub cmdGetDomain_Click () 
Dim ipAddress_h As Long ' the IP address, in host byte order 
Dim ipAddress_n As Long ' the IP address, in network byte order 
Dim sockinfo As WSADATA ' information about the Winsock implementation 
Dim pHostinfo As Long ' pointer to information about the host computer 
Dim hostinfo As HOSTENT ' information about the host computer 
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End Sub 

















' Verify that an IP address was entered. 
retval = SendMessage(hIPControl, IPM ISBLANK, 
If retval <> 0 Then 




















Exit Sub 





End If 











Dim domainName As String ' the primary domain name of the host computer 
Dim retval As Long ' generic return val 


ue 








ByVal CLng(0), ByVal CLIng (0)) 


Debug.Print "No IP address was entered!" 





' Get the IP address entered by the user and verify that all 





' four fields in the address wer ntered. 











retval = SendMessage(hIPControl, IPM GETADDRESS, ByVal CLng(0), ipAddress_h) 





























If retval < 4 Then 
Debug.Print "An incomplete IP address 
Exit Sub 








End If 








' Open up a Winsock v2.2 session. 
retval = WSAStartup(&H202, sockinfo) 
If retval <> 0 Then 











Exit Sub 





End If 














was entered!" 


Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 





' Convert the IP address into network byte order. 


ipAddress_n = htonl(ipAddress_h) 
' Get information about the host computer. 














pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_ 





NET) 














If pHostInfo = 0 Then 























Else 





' Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, 




















Debug.Print "Could not find a host with the specified IP address." 


Len (hostinfo) 


' Copy the host domain name into a string. 
domainName = Space(lstrien(hostinfo.h_name) ) 





retval = lstrcpy(domainName, hostinfo. 








End If 














' End the Winsock session. 
retval = WSACleanup () 





See Also 


CreateWindowEx, WM_CLOSE 


Category 
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h_name) 


Debug.Print "Domain name is: "; domainName 


Windows API Guide: DestroyWindow Function 


Windows 


Back to the Function list. 





Back to the Reference section. 


Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/d/destroywindow.html 
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Drawlicon Function 


Declare Function DrawIcon Lib "user32.dl11" (ByVal hDC As Long, ByVal x As 
Long, ByVal y As Long, ByVal hIcon As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Drawlcon displays an icon on a device. The icon's position is determined by a coordinate pair passed to the function 
identifying the coordinates of the upper-left corner of the icon. The icon is always drawn in its normal dimensions. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns 
a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hDC 
A handle to a device context to the device to draw the icon on. 


The x-coordinate of the point to position the upper-left corner of the icon's image at. 


y 
The y-coordinate of the point to position the upper-left corner of the icon's image at. 


hIcon 
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A handle to the icon to display. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Display the first icon (index 0) stored in the executable file 
' C:\MyApp\Prog.exe on window Forml. The icon must be destroyed after the 
' program finishes using it. 

Dim hIcon As Long ' handle to the function gotten from the executable file 
Dim retval As Long ' return value 











' Extract the first icon stored in the aforementioned executable file. 
hIcon = ExtractIcon(App.hInstance, "C:\MyApp\Prog.exe", 0) 

' Only attempt to display the icon if we successfully extracted it. 

If hIcon = 0 Then 








Debug.Print "Failed to extract the icon -- aborting." 
End ' terminate the program 
Else 


' Display the icon at coordinates (100, 75) on window Forml. 
retval = DrawIcon(Forml.hDC, 100, 75, hIcon) 
' Although the icon's image is still visible, the icon itself is not in use. 
' Therefore we destroy it to free up resources. 
retval = Destroyicon (hIcon) 

End If 








See Also 


DrawIconEx 


Category 


Icons 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 4, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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This page is at http://www.vbapi.com/ref/d/drawicon.html 
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DrawlconEx Function 
Declare Function DrawIconEx Lib "user32.d11" (ByVal hdc As Long, ByVal xLeft As 











Long, ByVal yTop As Long, ByVal hIcon As Long, ByVal cxWidth As Long, ByVal cyWidth 
As Long, ByVal istepIfAniCur As Long, ByVal hbrFlickerFreeDraw As Long, ByVal 
diFlags As Long) As Long 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


DrawlIconEx displays either an icon or a cursor (or a single frame of an animated cursor) on a device. The image's position is 
determined by passing the coordinates of the upper-left corner of the image. The function can stretch the image in either 
direction as well as specify other display parameters. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 

A handle to a device context to the device to draw the icon or cursor on. 
xLeft 

The x-coordinate of the point to position the upper-left corner of the icon's or cursor's image at. 
yTop 

The y-coordinate of the point to position the upper-left corner of the icon's or cursor's image at. 
hIcon 
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A handle to the icon or cursor to draw. 
cxWidth 
The width in pixels to stretch the icon's or cursor's image to. If this is 0, the image is drawn using either the icon's or 
cursor's width or the default width of the system, depending on the flags passed as diFlags. 
cyWidth 
The height in pixels to stretch the icon's or cursor's image to. If this is 0, the image is drawn using either the icon's or 
cursor's height or the default height of the system, depending on the flags passed as diFlags. 
istep]fAniCursor 
If hIcon is a handle to an animated cursor, this specifies the index of the particular frame to draw. Otherwise, this 
parameter is ignored. 
hbrFlickerFreeDraw 
A handle to the brush to use as the icon's or cursor's background. The background is added to the icon's or cursor's 
image using a flicker-free method. If this parameter is 0, the image is drawn directly onto the device without first 
adding a background. 
diFlags 
A combination of the following flags specifying how to draw the icon or cursor: 
DI_COMPAT 
Draw the icon or cursor using the system default image instead of the user-specified image. 
DI_DEFAULTSIZE 
If cxWidth and cyWidth are set to 0, draw the icon or cursor using the height and width settings defined by the 
system metrics. If this flag is not specified and the two parameters are set to 0, the icon or cursor is drawn 
using its own dimensions. 
DI_IMAGE 
Draw the icon's or cursor's image data onto the device. 
DI_ MASK 
Draw the icon's or cursor's mask data onto the device. 
DI_ NORMAL 
Draw the icon or cursor using both its image and mask, as usual. 





Constant Definitions 


Const DI_COMPAT = &H4 
Const DI_DEFAULTSIZE = &H8 


D 
D 
Const DI_IMAGE = &H2 
D 
D 











Const DI_MASK = &H1 
Const DI_NORMAL = &H3 








Example 


This code is licensed according to the terms and conditions listed here. 








' Extract all of the regular-sized icons from the file 
' C:\MyApp\Prog.exe. Display them in a row, stretching or shrinking them to 
' a width of 32 and a height of 64. Note how dynamically allocated arrays 























' are used to receive the icon handles. Draw all icons on a light-gray 
' background on the window Forml. 

Dim hIcons() As Long ' dynamic array to receive handles to the icons 
Dim numicons As Long ' number of regular icons in the file 

Dim hBrush As Long ' handle to the background brush to use 
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Dim c As Long ' counter variable 
Dim retval As Long ' return value 














Determine how many regular icons exist in the file and resize 
' the array accordingly. 
numicons = ExtractIconEx("C:\MyApp\Prog.exe", -1, ByVal 0, ByVal 0, 0) 














If numicons = 0 Then 

Debug.Print "No icons found in the file -- aborting." 

End ' abort the program if failure occurs 
End If 
ReDim hIcons(0 To numicons - 1) As Long ' resize the array to hold all the handles 
' Get a handle to the stock solid light gray brush to use for the background. 
hBrush = GetStockOb ject (LTGRAY_BRUSH) ' handle to the brush 





' Extract all of the icons to display. 
retval = ExtractIconEx("C:\MyApp\Prog.exe", numicons, hIcons (0), ByVal 0, 0) 








' Loop through each icon, displaying it as previously mentioned. 




















For c = 0 To numicons - 
' The x coordinate equals 32 * c. The y coordinate is always 0. 
' Display this particular icon. 
retval = DrawIconEx(Form1.hDC, 32 * c, 0, hIcons(c), 32, 64, 0, hBrush, DI_NORMAL) 
' Now destroy this icon since we no longer are using it. 
retval = DestroyIcon(hIcons(c)) 
Next c 


See Also 


DrawIcon 


Category 


Icons 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: August 5, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/d/drawiconex.html 
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Ellipse Function 


Declare Function Ellipse Lib "gdi32.dl1l" (ByVal hdc As Long, ByVal X1 
As Long, ByVal Y1 As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long 


Platforms: Win32s, Win 95/98, Win NT 


Ellipse draws an ellipse on a device. The two coordinate pairs passed to the function are not part of the 
ellipse itself, but define its bounding rectangle. The bounding rectangle is the smallest possible rectangle 
containing the ellipse. The ellipse is drawn using the device's current drawing color and is filled using the 
current filling color and brush, if any. The function returns 0 if it fails, or 1 if it succeeds. 


hdc 

The device context of the object to draw on. 
XI 

The x coordinate of the bounding rectangle's upper-left corner. 
Yl 

The y coordinate of the bounding rectangle's upper-left corner. 
X2 

The x coordinate of the bounding rectangle's lower-right corner. 
Y2 

The y coordinate of the bounding rectangle's lower-right corner. 
Example: 


' Draw a red ellipse with bounding rectangle (25,30)-(100,75) 
' on PictureBoxl 
Dim retval As Long ' return value 


PictureBoxl.ForeColor = RGB(255, 0, 0) " set color to draw in to red 
retval = Ellipse (PictureBoxl.hdc, 25, 30, 100, 75) 


See Also: AngleArc, Arc, ArcTo, Chord, Pie 
Category: Filled Shapes 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/e/ellipse.html 
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EndDoc Function 

















Declare Function EndDoc Lib "gdi32.dl1" (ByVal hdc As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


EndDoc informs the print spooler that the program has finished providing information for how to print a document. This 
function tells the spooler to finally print the document. The StartDoc and EndDoc functions must bracket all the code which 
draws the document on the printer (see the example for an illustration). 


Return Value 


If an error occured, the function returns either zero or a negative value (Windows NT, 2000: use GetLastError to get the error 
code). If successful, the function returns a positive value. 


Visual Basic-Specific Issues 
None. 


Parameters 


hdc 
A handle to a device context to the printer which the document is to be printed using. 





Example 


This code is licensed according to the terms and conditions listed here. 


' Print out 


pen on it. 


a page with an ellipse drawn with a thickened black 
The page is printed on the computer's default printer. 





ct ct 
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i 


declaratio 
tions to use pointe 
"kernel32 
lpString2 As Long) As Lo 
"kernel32 











The following are special 
manipulation func 
Declare Function lstrcpy Lib 
String, ByVal 
Declare Function lstrlen Lib 























As Long 


Variable declarations 














ns needed to allow string 
rs to strings. 

















-d1l1l" Alias “lstrcpyA" (ByVal lpStringl As 
ng 
-d1l1i" Alias "IstrlenA" (ByVal lpString As Long) 





































































































Dim hPrintDC As Long handle to the printer's device context 

Dim di As DOCINFO ' information about the document to print 

Dim hPen As Long ' handle to the pen to draw the ellipse with 

Dim hOldPen As Long ' handle to the printer's previously selected pen 

Dim buffer(0 To 3076 / 4) As Long ' 3076-byte buffer 

Dim pi2 As PRINTER INFO 2 ' receives info about the default printer 

Dim printret As Long ' receives the number of printers returned from EnumPrinters 
Dim spaceneeded As Long ' receives space requires for EnumPrinters 

Dim retval As Long ' return value 

' Get the device and driver names of the default printer. For a more detailed 

' description of the semi-confusing code below, consult the 

' EnumPrinters page. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 2, buffer(0), 3076, spaceneeded, 
printret) 


If 


retval 0 Then 
Debug.Print "No default printer is c 
End ' abort the program 
End If 




















onfigured." 





' Copy the device and driver names to 











the structure. All the 
eeded and is omitted here. 





























' other information retrieved is not n 
pi2.pPrinterName = Space (lstrlen (buffe 
retval = lstrcpy(pi2.pPrinterName, buf 
pi2.pDriverName = Space (lstrlen (buffer 
retval = lstrcpy(pi2.pDriverName, buff 




















Creat 
hPrintDC 





a device context to the print 
CreateDC("", pi2.pPrinterNa 
solid black brush with a th 


5, RGB(O, O0 








Create a 
hPen = CreatePen(PS_SOLID, 














Load information about the doc 
.cbSize Len (di) ' size of structu 


ument 





r(1))) 

fer(1)) 

(4))) 

er (4) ) 

er, uSing its default initialization. 
me, 0, ByVal CLng(0)) 





ickness of 5. 
, 0)) 

to print into the structure. 
re 














.lpszDocName = "Printer API Demonstr 
.lpszOutput 0. ' do not print toa 
.lpszDatatype = ' data type of f 


.fwType 0 no additional informa 











' 





i document 





ation" name of 
file 
ile doesn't apply 
tion 








Begin 
tval 


the print job. 
StartDoc(hPrintDC, di) 

Begin the first and only page to pri 
tval = StartPage (hPrintDC) 

Select the pen for use with the prin 








re 





























re 


k 
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hOldPen = SelectObject (hPrintDC, hPen) 
' Draw an ellipse with bounding rectangle corners (1000,1500)-(2000, 3000) 


retval = Ellipse(hPrintDC, 1000, 1500, 2000, 3000) 
' Restore the printer's previously selected pen. 

































































retval = SelectObject (hPrintDC, hOldPen) 

' End information about the first and only page. 
retval = EndPage(hPrintDC) 

' End information about the document. 

retval = EndDoc (hPrintDC) 








' The printer will now begin printing the document. 





' Delete the pen created for drawing. 
retval = DeleteObject (hPen) 

" Delete the device context to the printer. 
retval = DeleteDC (hPrintDC) 






































See Also 


StartDoc 


Category 


Printers 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


Last Modified: November 2, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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EndPage Function 

















Declare Function EndPage Lib "gdi32.dll1" (ByVal hDC As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


EndPage informs the print spooler that the program has finished drawing the contents of a printed page. The StartPage and 
EndPage functions must bracket all code which draws the contents of the printed page. The print spooler must have already 
been informed that it is receiving a document to be printed via StartDoc before drawing the page had begun. The printer does 
not actually print the page until the print spooler is told via EndDoc that the entire document is complete. 





Return Value 


If an error occured, the function returns either zero or a negative value (Windows NT, 2000: use GetLastError to get the error 
code). If successful, the function returns a positive value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hDC 
A handle to a device context to the printer being used to print the document. 


Example 


This code is licensed according to the terms and conditions listed here. 


Print out a page with an ellipse drawn with a thickened black 
pen on it. The page is printed on the computer's default printer. 


' 
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St 





As 


The follo 


wing are special declarations needed to allow string 








manipulat 


Declare Function lstrcpy Lib 








ion functions to use pointers to strings. 


"kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl As 





ring, ByVal lpString2 As Long) 


Long 








' Variable declarations 


























As Long 
Declare Function lstrlen Lib "kernel32.d11" Alias "lIstrlenA" (ByVal lpString As Long) 













































































































































































Dim hPrintDC As Long ' handle to the printer's device context 
Dim di As DOCINFO ' information about the document to print 
Dim hPen As Long ' handle to the pen to draw the ellipse with 
Dim hOldPen As Long ' handle to the printer's previously selected pen 
Dim buffer(0 To 3076 / 4) As Long ' 3076-byte buffer 
Dim pi2 As PRINTER INFO 2 ' receives info about the default printer 
Dim printret As Long ' receives the number of printers returned from EnumPrinters 
Dim spaceneeded As Long ' receives space requires for EnumPrinters 
Dim retval As Long ' return value 
' Get the device and driver names of the default printer. For a more detailed 
' description of the semi-confusing code below, consult the 
' EnumPrinters page. 
retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 2, buffer(0), 3076, spaceneeded, 
printret) 
If retval = 0 Then 
Debug.Print "No default printer is configured." 
End ' abort the program 
End If 
' Copy the device and driver names to the structure. All the 
' other information retrieved is not needed and is omitted here. 
pi2.pPrinterName = Space (lstrlen (buffer (1))) 
retval = lstrcpy(pi2.pPrinterName, buffer (1)) 
pi2.pDriverName = Space (lstrlen (buffer (4))) 
retval = lstrcpy(pi2.pDriverName, buffer (4)) 
' Create a device context to the printer, using its default initialization. 
hPrintDC = CreateDC("", pi2.pPrinterName, 0, ByVal CLng(0)) 
' Create a solid black brush with a thickness of 5. 








hPen = CreatePen(PS_ SOLID, 5, RGI 


re 


re 











Load info 
.cbSize = 
.lpszDocN 
.lpszOutp 
-lpszData 
.fwType = 











Begin the 
tval = St 


B(0, 





0, 0)) 


























rmation about the document to print into the structure. 
Len (di) " size of structure 

ame = "Printer API Demonstration" " name of document 
ut = 0 ' do not print to a file 
type = ™" ' data type of file doesn't apply 

0 ' no additional information 

print job. 





artDoc(hPrintDC, di) 








Begin the 





Select th 




















first and only page to print. 
tval = StartPage (hPrintDC) 


e pen for use with the printer. 
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hOldPen = SelectObject (hPrintDC, hPen) 

' Draw an ellipse with bounding rectangle corners (1000,1500)-(2000, 3000) 
retval = Ellipse(hPrintDC, 1000, 1500, 2000, 3000) 

' Restore the printer's previously selected pen. 

retval = SelectObject (hPrintDC, hOldPen) 


vas 




















' End information about the first and only page. 
retval = EndPage (hPrintDC) 
' End information about the document. 
retval = EndDoc(hPrintDC) 






































' The printer will now begin printing the document. 





' Delete the pen created for drawing. 
retval = DeleteObject (hPen) 

" Delete the device context to the printer. 
retval = DeleteDC (hPrintDC) 






































See Also 


StartPage 


Category 


Printers 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: November 5, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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EnumChildWindows Function 











Declare Function EnumChildWindows Lib "user32.d11" (ByVal hWndParent As Long, ByVal 
lpEnumFunc As Long, ByVal lParam As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


EnumChild Windows enumerates and provides handles to all of the child windows of a given window. This function will 





also enumerate any children of the child windows. Each time a child window is located, the function passes that handle to a 
program-defined callback function. The function continues doing so until all child windows have been enumerated, or until 
the process has been aborted. 





Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWndParent 

A handle to the parent window to enumerate the child windows of. 
[pEnumFunc 

A pointer to the application-defined callback function EnumChildProc. 
lParam 

An additional value to pass to the application-defined callback function. 


Example: 
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' Display the window title of all children of window MDIForml. This 


" task is given to the callback function, which will receive each handle 
individually. 











' *** Place this code in a module. This is the callback function. *** 
' This function displays the title bar text of the window identified by hwnd. 
Public Function EnumChildProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 





















































Dim slength As Long, wintext As String ' window title text length and buffer 

Dim retval As Long ' return value 

Static winnum As Integer ' counter keeps track of how many windows have been 
enumerated 

winnum = winnum + 1 ' one more window enumerated.... 

slength = GetWindowTextLength(hwnd) + 1 ' get length of title bar text 

buffer = Space(slength) ' make room in the buffer 

retval = GetWindowText (hwnd, buffer, slength) ' get title bar text 

Debug.Print "Window #"; winnum; " : "; ' display number of enumerated window 

Debug.Print Left (buffer, slength - 1) ' display title bar text of enumerated 
window 

EnumChildProc = 1 ' nonzero return value means continue enumeration 





End Function 





' xxx Place this code wherever you want to enumerate the windows. *** 











Dim retval As Long ' return value 

' Use the above callback function to list all of th numerated windows. Note that 
lParam is 

' set to 0 because we don't need to pass any additional information to the function. 








retval = EnumChildWindows (MDIForml.hWnd, AddressOf EnumChildProc, 0) 








See Also 


EnumThread Windows, EnumWindows 


Category 


Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 15, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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This page is at http://www.vbapi.com/ref/e/enumchildwindows.html 
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EnumDisplaySettings Function 


Declare Function EnumDisplaySettings Lib "user32.d11" Alias 
"EnumDisplaySettingsA" (ByVal lpszDeviceName As String, ByVal iModeNum As 
Long, lpDevMode As DEVMODE) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.51 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


EnumDisplaySettings gets the display settings of one of a display device's graphics modes. Specifically, the 
function gets the display mode's resolution, color depth, and frequency, along with some additional information. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (Windows 
NT/2000: use GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


lpszDeviceName 
Windows 95, 98: This must be a null string. Windows NT, 2000: If this is a null string, the current display 
device is used. Otherwise, this is the device name of the display device to examine. The string is of the form 
"\\.\DisplayX", where X is 1, 2, or 3. 

iModeNum 
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The number of the graphics mode to retrieve information about. This could also be one of the following 
flags specifying a graphics mode: 
ENUM_CURRENT_SETTINGS 
Get information about the current display settings. 
ENUM_REGISTRY_SETTINGS 
Get information about the display settings stored in the registry. 
IpDevMode 
Receives information about the graphics mode. Only the dmBitsPerPixel, dmPelsWidth, dmPelsHeight, 
dmDisplayFlags, and dmDisplayFrequency members have useful data in them. Before calling the function, 
this structure's dmSize member must be properly set. 


Constant Definitions 














Const ENUM_CURRENT_SETTINGS = -1 
Const ENUM_REGISTRY_SETTINGS = -2 
Example 


Display information about the current display settings for the monitor. To use this example, place a command 
button named Command! on a form window. 


This code is licensed according to the terms and conditions listed here. 


' 4 


Declarations and such needed for the example: 

(Copy them to the (declarations) section of a module.) 
Public Type DEVMODE 

mDeviceName As String * 32 

mSpecVersion As Integer 

mDriverVersion As Integer 

Size As Integer 

DriverExtra As Integer 

Fields As Long 
mOrientation As Integer 
mPaperSize As Integer 
mPaperLength As Integer 
mPaperWidth As Integer 
mScale As Integer 

mCopies As Integer 
mDefaultSource As Integer 
mPrintQuality As Integer 
mColor As Integer 

mDuplex As Integer 
mYResolution As Integer 
mTTOption As Integer 
mCollate As Integer 











=e 





3 
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dmFormName As String * 32 

mUnusedPadding As Integer 

mBitsPerPixel As Integer 

lsWidth As Long 

lsHeight As Long 

mDisplayFlags As Long 

DisplayFrequency As Long 

The following only appear in Windows 95, 98, 2000 
TCMMethod As Long 

CMIntent As Long 

mMediaType As Long 

mDitherType As Long 

mReservedl As Long 

mReserved2 As Long 

The following only appear in Windows 2000 
mPanningWidth As Long 

mPanningHeight As Long 











33 
U tU 
® 0 





"POGES 


3 











3 








-aooo 








d 
d 
End Type 
Public Declare Function EnumDisplaySettings Lib "user32.dll" Alias 
"EnumDisplaySettingsA" (ByVal lpszDeviceName As String, 

ByVal iModeNum As Long, lpDevMode As DEVMODE) As Long 
Public Const ENUM_CURRENT_SETTINGS = -1 
Public Const ENUM_REGISTRY_SETTINGS = -2 




















' *** Place the following code inside the form window. *** 





Private Sub Commandl1_Click() 
Dim dm As DEVMODE ' info about the display device 
Dim retval As Long ' return value 





' Initialize the structure. 

dm.dmSize = Len (dm) 

' Get the display settings for the current monitor and mode. 

retval = EnumDisplaySettings (vbNullString, ENUM_CURRENT_SETTINGS, dm) 
' Print some information about the display. 








Debug.Print "- Bits Per Pixel: "; dm.dmBitsPerPixel 
Debug.Print "- Width (Pixels): "; dm.dmPelsWidth 
Debug.Print "- Height (Pixels):"; dm.dmPelsHeight 
Debug.Print "- Display Freq.: "; dm.dmDisplayFrequency 


End Sub 
See Also 
ChangeDisplaySettings 


Category 
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Devices 


Back to the Function list. 
Back to the Reference section. 


Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/e/enumdisplaysettings.html 
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shop.com | 
EnumFontFamilies Function 
Declare Function EnumFontFamilies Lib "gdi32.dl1" Alias "EnumFontFamiliesA" (ByVal 


























hdc As Long, ByVal lpszFamily As Any, ByVal lpEnumFontFamProc As Long, ByVal lParam 
As Long) As Long 


Platforms 


e Windows 95: Supported but Obsolete; use EnumFontFamiliesEx instead. 

e Windows 98: Supported but Obsolete; use EnumFontFamiliesEx instead. 

e Windows NT: Requires Windows NT 3.1 or later but Obsolete under Windows NT 4.0 or later; use 
EnumFontFamiliesEx instead. 





e Windows 2000: Supported but Obsolete; use EnumFontFamiliesEx instead. 
e Windows CE: Not Supported. 





Description & Usage 


EnumFontFamilies enumerates all of the fonts available for use on a device which use a certain typeface. The only trait that 
the function looks for in the enumerated fonts is that it uses the specified typeface. The enumerated fonts are individually 
passed to a callback function for processing. 





Return Value 

The function returns whatever the final call to the callback function returned. 
Visual Basic-Specific Issues 

When passing 0 as /pszFamily, the expression CLng(0) must be used. 


Parameters 


hdc 
A handle to a device context to the device to enumerate the fonts of. 





IpszFamily 
The name of the font typeface which the enumerated fonts must use. To instead enumerate a single font from each 
possible typeface, pass O for this parameter (not an empty string!). 

[pEnumFontFamProc 
A pointer to the EnumFontFamProc callback function which processes the information about each font that is 


enumerated. 
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lParam 
A value to pass to the function specified by JpEnumFontFamProc. 


Example 


This code is licensed according to the terms and conditions listed here. 





Enumerate some of 
These fonts must hav 








the fonts available 


the Times 


New Roman 








xxx Place the following code in a module. 


The following callba 





ck 



































typeface. 


KkK* 


for window Forml. 


Display some information about each font as it is enumerated. 











function processes the enumerated 























fonts. 














Public Function EnumFontFamProc (ByVal lpelf As Long, ByVal lpntm As Long, 
FontType As Long, ByVal lParam As Long) As Long 
Dim elf As ENUMLOGFONT ' receives information about the font 
Dim ntm As NEWTEXTMETRIC ' receives text metrics for TrueType fonts 
Dim tm As TEXTMETRIC ' receives text metrics for non-TrueType fonts 


vbNullChar) - 



























































Debug.Print "Font 
1); 
Debug.Print " 
' Display 





(Tr 




















Name: "; Le 





























ueType font 


the style of the font 


ya 


InStr (el 


Then 





' Copy the font information into the appropriate structure. 
CopyMemory elf, ByVal lpelf, Len (elf) 
' If the font is TrueType, use the following code. 
If (FontType And TRUETYPE_FONTTYPE) = TRUETYPE_FONTTYPE 
' Copy the text metrics into the appropriate structure. 
CopyMemory ntm, ByVal lpntm, Len(ntm) 
' Display the name of the font 


(removing empty space from it). 
ft (elf.elfFullName, 











(again removing empty space). 
































Debug.Print "Font Style: "; Left(elf.elfStyle, InStr(elf.elfStyle, 
' Display the average character width. 
Debug.Print "Average Character Width:",; ntm.tmAveCharWidth 
' Display the maximum character width. 
Debug.Print "Maximum Character Width:", ntm.tmMaxCharWidth 
' If the font is not TrueType, use the following code. 
Else 





" Copy the text me 
CopyMemory tm, 














ByVal lpntm, 


trics into 







































































the appropriate structure. 
Len (tm) 























f.elfFullName, 


ByVal 


vbNullChar) 


' Display the name of the font (removing empty space from it). 
Debug.Print "Font Name: "; 
Debug.Print Left (elf.elfLogFont.1lfFaceName, InStr(elf.elfLogFont.1lfFaceName, 
vbNullChar) - 1); 
' Display whether the font is a device or a raster font. 
If FontType = DEVICE_FONTTYPE Then 
Debug.Print " (Device font)" 
ElseIf FontType = RASTER_FONTTYPE Then 
Debug.Print " (Raster font)" 
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End If 
Debug.Print "Font Style does not apply for this font." 
' Display the average character width. 
Debug.Print "Average Character Width:", tm.tmAveCharWidth 
' Display the maximum character width. 

Debug.Print "Maximum Character Width:", tm.tmMaxCharWidth 


















































End If 

Debug.Print "***" ' separator 

' Tell EnumFontFamilies to continue enumeration. 
EnumFontFamProc = 1 








End Function 





' ***x Place this code wherever you want the enumerate the fonts. *** 
Dim retval As Long ' return value 














' Enumerate all the fonts with the Times New Roman 
' typeface which are available on Forml. 
retval = EnumFontFamilies (Forml.hDC, "Times New Roman", AddressOf EnumFontFamProc, 




















Debug.Print "Enumeration complete." 





See Also 


EnumFontFamiliesEx 





Category 
Fonts & Text 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: October 29, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/e/enumfontfamilies.html 
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EnumFontFamiliesEx Function 

















Declare Function EnumFontFamiliesEx Lib "gdi32.dl1" Alias "EnumFontFamiliesExA" (ByVal 
hdc As Long, lpLogfont As LOGFONT, ByVal lpEnumFontFamExProc As Long, ByVal lParam As 
































Long, ByVal dwFlags As Long) As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 4.0 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


EnumFontFamiliesEx enumerates all of the fonts available for use on a device which match a basic description. The function 
enumerates fonts based on their character sets and/or typeface styles (or simply all fonts). The function treats identical fonts with 
different character sets as two different fonts (for example, Times New Roman with the ANSI character set is considered a 
different font than Times New Roman with the Cyrillic character set). The fonts are not enumerated in any obvious order. 


Return Value 


The function returns whatever the final call to the callback function returned. 





Visual Basic-Specific Issues 


None. 


Parameters 


hdc 
A handle to a device context to the device to enumerate the available fonts of. 

lpLogfont 
Identifies the character set and/or typeface name (or neither) of the fonts to enumerate. The ./fCharset member identifies 
the character set of the fonts to enumerate, or DEFAULT_CHARSET to ignore the character set. The ./fFaceName 
member identifies the typeface name of the fonts to enumerate, or an empty string to ignore the typeface name. The 
.[fPitchAndFamily member is not used but must be zero. All other members are ignored. 

[pEnumFontFamExProc 
A pointer to the EnumFontFamExProc callback function which processes the information about each font that is 
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enumerated. 


[Param 


A value to pass to the function identified by JpEnumFontFamExProc. 
dwFlags 
Reserved -- set to 0. 


Example 





This code is licensed according to the terms and conditions listed here. 








Enumerate some of the 





' These fonts must have 


' Times New Roman type! 





' each font as it is en 














' xxx Place the followi 


' The 














following callbac 











fonts available for window Forml. 
the ANSI character set and have the 
ace. Display some information about 
umerated. 














ng code in a module. *** 
k function processes the enumerated fonts. 














Public Function EnumFon 








~ 








tFamExProc (ByVal lpelfe As Long, ByVal lpntme As Long, ByVal 

















FontType As Long, ByVal 





Dim ntmx As NEWTEXTME 
Dim tm As TEXTMETRIC 








Dim elfx As ENUMLOGFO 


lParam As Long) As Long 
NTEX ' receives information about the font 















































TRICEX ' receives text metrics for TrueType fonts 






































' receives text metrics for non-TrueType fonts 











" Copy the font infor 
CopyMemory elfx, ByVa 














mation into the appropriate structure. 
1 lpelfe, Len(elfx) 
































CopyMemory ntmx, 


(FontType And TRUE 





the font is True 





Type, use the following code. 




















TYPE_FONTTYPE) = TRUETYPE_FONTTYPE Then 











T 














Copy the text met 











Display the name 


Debug.Print "Font N 
vbNullChar) - 1); 
Debug.Print " (Tru 














Display the style 












































rics into the appropriate structure. 





ByVal lpntme, Len(ntmx) 

















of the font (removing empty space from it). 
ame: "; Left (elfx.elfFullName, InStr(elfx.elfFullName, 
































eType font)" 
of the font (again removing empty space). 





























Debug.Print "Font Style: "; Left (elfx.elfStyle, InStr(elfx.elfStyle, vbNullChar) 








































































































1) 
' Display the average character width. 
Debug.Print "Average Character Width:", ntmx.ntmTm.tmAveCharWidth 
' Display the maximum character width. 
Debug.Print "Maximum Character Width:", ntmx.ntmTm.tmMaxCharWidth 
' If the font is not TrueType, use the following code. 
Else 
" Copy the text metrics into the appropriate structure. 
CopyMemory tm, ByVal lpntme, Len (tm) 
' Display the name of the font (removing empty space from it). 
Debug.Print "Font Name: "; 
Debug.Print Left (elfx.elfLogFont.1fFaceName, InStr(elfx.elfLogFont.1fFaceName, 
vbNullChar) - 1); 

















Display whether t 








he font is a device or a raster font. 














FontType = DEVIC 





E FONTTYPE Then 
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Debug.Print " (Device font)" 

ElseIf FontType = RASTER_FONTTYPE Then 
Debug.Print " Raster font)" 

End If 
Debug.Print "Font Style does not apply for this font. 
' Display the average character width. 
Debug.Print "Average Character Width:"; tm.tmAveCharWidth 
' Display the maximum character width. 
Debug.Print "Maximum Character Width:", tm.tmMaxCharWidth 








T 





























~ 

























































































End If 

Debug.Print "***" ' separator 

' Tell EnumFontFamiliesEx to continue enumeration. 
EnumFontFamExProc = 1 





End Function 








' xxx Place this code wherever you want the enumerate the fonts. *** 






















































































Dim 1f As LOGFONT ' describes enumeration attributes 

Dim retval As Long ' return value 

' Initialize the structure to describe the fonts we want. 

1lf.1fCharset = ANSI_CHARSET ' fonts with the ANSI character set 

1lf.lfFaceName = "Times New Roman" & vbNullChar ' fonts with the Times New Roman 
typeface 

1f.1fPitchAndFamily = 0 ' this must be 0 

' Enumerate such fonts available on window Forml. 





retval = EnumFontFamiliesEx(Forml.hDC, lf, AddressOf EnumFontFamExProc, 0, 0) 












































Debug.Print "Enumeration complete." 


See Also 


EnumFontFamilies 





Category 
Fonts & Text 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: October 23, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/enumfontfamiliesex.html 
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EnumJobs Function 
Declare Function EnumJobs Lib "winspool.drv" Alias "EnumJobsA" (ByVal hPrinter As 

















Long, ByVal FirstJob As Long, ByVal NoJobs As Long, ByVal Level As Long, pJob As 
Long, ByVal cbBuf As Long, pcbNeeded As Long, pcReturned As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


EnumJobs enumerates all of the print jobs pending for a given printer. The function can retrieve either (relatively) brief or 
detailed information describing each job in the print queue for that printer. Note that, instead of placing the information 
directly into the corresponding structures, the function places the information into an array. The array's contents must then be 
transfered to one or more structures. In order to determine how much space is necessary to receive the information about each 
print job, first call the function with cbBuf set to 0. The function will set the variable passed as pcbNeeded to the size in bytes 
of the array necessary hold the information. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non-zero 
value. 


Visual Basic-Specific Issues 


The data retrieved by the function cannot be directly copied into structure(s) using CopyMemory or some other method. 


Instead, each (desired) member of the structure must manually be copied from the array to the structure, using the 
corresponding array indices. Each structure's contents appear sequentially in the array, and one structure immediately follows 
another. See the example code for a demonstration on how this is done. 


Additionally, strings are not stored directly. Instead, the data placed into the array contains pointers to strings whenever 
necessary. The string manipulation API functions Istrlen and Istrcpy are needed to copy the pointed-to string into the structure's 





string data member(s). Again, see the example for a clearer demonstration. However, to copy structures stored under the 
original structure, CopyMemory can be used. Of course, numeric data members can be copied directly from the array to the 
structure. 
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Finally, when determining the space needed for the array, both pJob and cbBuf must be set to 0. To set pJob to 0, the 
expression ByVal 0 must be used. 


Parameters 


hPrinter 
A handle to the printer to enumerate the print jobs of. 

FirstJob 
The zero-baded position in the print queue to begin print job enumeration from. To enumerate all jobs, of course set this 
to 0. To enumerate everything except the first job, set this to 1 (identifying the second print job), etc. 

NoJobs 
The maximum number of print jobs to enumerate. 

Level 
Identifies the format of the information placed into the array passed as pJob. If this is 1, the data is in the format of 
JOB_INFO_1 structures. If this is 2, the data is in the format of JOB _INFO_2 structures. 

pJob 
An array which receives all the information about the print jobs retrieved by the function. The format of this data is 
specified in Level. The array must be large enough to receive all the data. If you are setting cbBuf to 0, this must also be 
0. 

cbBuf 
The size in bytes of the array passed as pJob. To determine how large the array must be, set this to 0. 

pcbNeeded 
Receives the number of bytes of data copied into the array passed as pJob. If the function failed, this is the minimum 
size in bytes which the array passed as pJob must be. 

pcReturned 
Receives the number of print jobs retrieved by the function. 


Example 


' 


This code is licensed according to the terms and conditions listed here. 





' Display a little information about each print job in the 


P 


' queue for the default printer. Note how both EnumPrinters and 





























' EnumJobs first copy the data into the arrays before placing 
' the information into the desired structure. 

























































































Dim pil As PRINTER INFO 1 ' holds a little information about the printer 

Dim hPrinter As Long ' handle to the default printer once it is opened 

Dim arraybuf() As Long ' resizable array used as a buffer 

Dim jobinfo As JOB INFO 2 ' holds detailed info about a print job 

Dim needed As Long ' receives space needed in the buffer array 

Dim numitems As Long ' receives the number of items returned 

Dim lendivfour As Long ' the size in Long-type units of the jobinfo structure 
Dim c As Long ' counter variable 

Dim retval As Long ' return value 




















' —— Get the name of the default printer. -- 

' Determine how much space is needed to get the printer information. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 1, ByVal 0, 0, needed, numitems) 
' Resize the array buffer to the needed size in bytes. 
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ReDim arraybuf(0 To needed / 4 - 1) ' remember each element is 4 bytes 

' Retrieve the information about the default printer. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 1, arraybuf(0), needed, needed, 
numitems) 

" Copy the printer name into the structure. The rest is unnecessary. 

pil.pName = Space (lstrlen(arraybuf (2) )) 

retval = lstrcpy(pil.pName, arraybuf (2) ) 

' —— Obtain a handle to the default printer (using default configuration). -- 
retval = OpenPrinter(pil.pName, hPrinter, ByVal CLng(0)) 

' —— Enumerate the default printer's print jobs currently queued. -- 




















Determine how much space is needed to get the 

















For each print job, 












































copy i 


print Jobs" information. 

















tval = EnumJobs(hPrinter, 0, 100, 2, ByVal 0, 0, needed, numitems) 
Resize the array buffer to the needed size in bytes. 
Dim arraybuf(0 To needed / 4 - 1) ' remember each element is 4 bytes 
Retrieve the information about the print jobs. 
tval = EnumJobs(hPrinter, 0, 100, 2, arraybuf(0), needed, needed, numitems) 
Display the number of print jobs currently in the queue. 
numitems > 0 Then 
Debug.Print "There are"; numitems; "print jobs currently in the queue." 
se 


Debug.Print "No print jobs are currently in the queue." 
End If 





ts data into the structure. Then display selected 






















































































' information from the structure. For brevity, this example copies only a 
' few of the data members into the structure. 
lendivfour = Len(jobinfo) / 4 ' this is the number of elements for each structure in 
the array 
For c = 0 To numitems - 1 ' loop through each item 
' Copy selected information into the structure: the job ID number, the 
' name of the user who printed it, the total number of pages, and 
' the time it was added into the queue. 
jobinfo.JobID = arraybuf (lendivfour * c) ' the first element of the array chunk 
jobinfo.pUserName = Space(lstrlen(arraybuf (lendivfour * c + 3))) ' fourth element 
retval = lstrcpy(jobinfo.pUserName, arraybuf (lendivfour * c + 3)) 
jobinfo.TotalPages = arraybuf(lendivfour * c + 18) ' nineteenth element 
CopyMemory jobinfo.Submitted, arraybuf(lendivfour * c + 20), Len(jobinfo.Submitted) 
' twenty-first element 
' Display the copied information. 
Debug.Print "Job ID number:",; jobinfo.JobID 
Debug.Print "Printed by user: "; jobinfo.pUserName 
Debug.Print "Number of pages:"; jobinfo.TotalPages 
Debug.Print "Placed in queue on: "; 
' (display the date and time stored in jobinfo.Submitted) 
Debug.Print jobinfo.Submitted.wMonth; "-"; jobinfo.Submitted.wDay; "-"; 
jobinfo.Submitted.wYear; " "; 
Debug.Print jobinfo.Submitted.wHour; ":"; jobinfo.Submitted.wMinute; ":"; 
jobinfo.Submitted.wSecond; " GMT" 
Next c 
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' Close the printer handle now that it is no longer needed. 
retval = ClosePrinter (hPrinter) 








Category 


Printers 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





Last Modified: November 24, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/enumjobs.html 
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shop.com | 
EnumPrinters Function 
Declare Function EnumPrinters Lib "winspool.drv" Alias "EnumPrintersA" (ByVal flags 












































As Long, ByVal name As String, ByVal Level As Long, pPrinterEnum As Long, ByVal cdBuf 





As Long, pcbNeeded As Long, pcReturned As Long) As Long 
Platforms: Win 95/98, Win NT 


EnumPrinters finds and returns information about one or more printers which the computer has access to. These include both 
local printers (physically connected to the machine) and network printers (accessible via the network). Under Win 95/98, the 
information can be passed in a PRINTER_INFO_1, PRINTER _INFO_2, or PRINTER_INFO_S5 structure. Under Win NT, the 
information can be passed in a PRINTER_INFO_1, PRINTER _INFO_2, or PRINTER_INFO_4 structure. Note that structures 
4 and 5 are the quickest ones to use. The attributes of the chosen structure determine what kinds of information about the 
printer(s) is returned. The information itself is put into the array passed as pPrinterEnum, which can then be copied into an 
array of data structures. The function returns 1 if successful, or 0 if an error occured. 
































Note for Visual Basic users: Due to limitations in the Visual Basic language, it is impossible to pass an array of 
PRINTER_INFO_* structures as pPrinterEnum -- the array must be of Long-type elements. Also, for some reason the 
CopyMemory function cannot be used to successfully transfer the array information into the structure. Instead, each individual 
member of the data structure must be set manually. Look at the two examples for details how. In order to convert a Long-type 
string pointer (in the array) to a string, variants of the Istrcpy and Istrlen function must be used. Again, see the examples. 
CopyMemory, however, can be used to copy the data structures which make up parts of the PRINTER_INFO_2 data structure. 











flags 
One or more of the following flags specifying which printers to find information about (note that 
PRINTER_ENUM_LOCAL and PRINTER_ENUM_CONNECTIONS are the only valid flags when using 
PRINTER_INFO_4): 
PRINTER_ENUM_CONNECTIONS = &H4 
Win NT only: Get information about the network printers which the computer has made connections to. 
PRINTER_ENUM_DEFAULT = &H1 
Win 95/98 only: Get information about the computer's default printer. 
PRINTER_ENUM_LOCAL = &H2 
Get information about local printers (the ones directly connected to the system). Win 95/98 for some reason also 
considers network printers to be local. 
PRINTER_ENUM_NAME = &H8 
Get information about all the printers under the network domain specified by name. 
PRINTER_ENUM_NETWORK = &H40 
Win NT only: Get information about all the printers under the computer's domain in the network. This only 
works with the PRINTER_INFO_1 structure. 
PRINTER_ENUM_REMOTE = &H10 
Win NT only: Same as PRINTER_ENUM_NETWORK. 
PRINTER_ENUM_SHARED = &H20 
Get information about all the printers with the shared attribute. 

















name 
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The name of the network domain to look under, if applicable. See flags to see when this would be used. If not used, set 
this parameter to an empty string. 

Level 
Specifies which PRINTER_INFO_* structure to use. For Win 95/98, this can be 1, 2, or 5. For Win NT, this can be 1, 
2, or 4. 

pPrinterEnum 
An array which receives all of the information found by the function. This needs to be copied manually into the 
PRINTER_INFO_* structure. 

cdBuf 
The size in bytes of the array passed as pPrinterEnum. 

pcbNeeded 
If successful, receives the number of bytes of information the function found. If unsuccessful, receives the number of 
bytes that pPrinterEnum must have in order to receive all of the information. 

pcReturned 
Receives the number of printers found by the function. 


Example #1: 





' Get information about all of the local printers using structure 1. Note how 

" the elements of the array are loaded into an array of data structures manually. 
Also 

' note how the following special declares must be used to allow numeric string 
pointers 
" to be used in place of strings: 

Declare Function Ilstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl As 

















n 











String, ByVal lpString2 As Long) As Long 
Declare Function lstrien Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString As Long) 










































































































































































As Long 
Dim longbuffer() As Long ' resizable array receives information from the function 
Dim printinfo() As PRINTER INFO 1 ' values inside longbuffer() will be put into here 
Dim numbytes As Long ' size in bytes of longbuffer () 
Dim numneeded As Long ' receives number of bytes necessary if longbuffer() is too 
small 
Dim numprinters As Long ' receives number of printers found 
Dim c As Integer, retval As Long ' counter variable & return value 
' Get information about the local printers 
numbytes = 3076 ' should be sufficiently big, but it may not be 
ReDim longbuffer(0 To numbytes / 4) As Long ' resize array -- note how 1 Long = 4 
bytes 
retval = EnumPrinters (PRINTER_ENUM_LOCAL, "", 1, longbuffer(0), numbytes, numneeded, 
numprinters) 
If retval = 0 Then ' try enlarging longbuffer() to receive all necessary information 
numbytes = numneeded 
ReDim longbuffer(0 To numbytes / 4) As Long ' make it large enough 














retval = EnumPrinters (PRINTER_ENUM_LOCAL, "", 1, longbuffer(0), numbytes, 
numneeded, numprinters) 


























If retval = 0 ' failed again! 
Debug.Print "Could not successfully enumerate the printes." 
End ' abort program 

End If 
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End If 
" Convert longbuffer() data into printinfo() 
ReDim printinfo(0 To numprinters - 1) As PRINTER INFO 1 ' room for each printer 
For c = 0 To numprinters - 1] ' loop, putting each set of information into each 
element 

' longbuffer(4 * c) = .flags, longbuffer(4 * c + 1) = .pDescription, etc. 


' For each string, the string is first buffered to provide enough room, and then 
the string is copied. 










































































printinfo(c).flags = longbuffer(4 * c) 
printinfo(c).pDescription = Space (lstrilen(longbuffer(4 * c + 1))) 
retval = lstrcpy(printinfo(c).pDescription, longbuffer(4 * c + 1)) 
printinfo(c).pName = Space(lstrlen(longbuffer(4 * c + 2))) 
retval = lstrcpy(printinfo(c).pName, longbuffer(4 * c + 2)) 
printinfo(c).pComment = Space(lstrlen(longbuffer(4 * c + 3))) 
retval = lstrcpy(printinfo(c).pComment, longbuffer(4 * c + 3)) 
Next c 
' Display name of each printer 
For c = 0 To numprinters - ] 
Debug.Print "Name of printer"; c + 1; " is: "; printinfo(c) .pName 
Next c 
Example #2: 
' Get information about all of the local printers using structure 2. Note how 


' the elements of the array are loaded into an array of data structures manually. 


Also 





" note how the following special declares must be used to allow numeric string 





pointers 
' to be 





Declare Function lstrcpy Lib "kernel32.d11" Alias " 





used in place of strings: 


n 








trcepyA" (ByVal lpStringl As 



































































































































String, ByVal lpString2 As Long) As Long 

Declare Function lstrlen Lib "kernel32.d11" Alias "lIstrlenA" (ByVal lpString As Long) 
As Long 

Dim longbuffer() As Long ' resizable array receives information from the function 
Dim printinfo() As PRINTER INFO 2 ' values inside longbuffer() will be put into here 
Dim numbytes As Long ' size in bytes of longbuffer () 

Dim numneeded As Long ' receives number of bytes necessary if longbuffer() is too 
small 

Dim numprinters As Long ' receives number of printers found 

Dim c As Integer, retval As Long ' counter variable & return value 

' Get information about the local printers 

numbytes = 3076 ' should be sufficiently big, but it may not be 

ReDim longbuffer(0 To numbytes / 4) As Long ' resize array -- note how 1 Long = 4 
bytes 

retval = EnumPrinters (PRINTER_ENUM_LOCAL, "", 2, longbuffer(0), numbytes, numneeded, 
numprinters) 

If retval = 0 Then ' try enlarging longbuffer() to receive all necessary information 
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numbytes = numneeded 

ReDim longbuffer(0 To numbytes / 4) As Long ' make it large enough 

retval = EnumPrinters (PRINTER_ENUM_LOCAL, "", 2, longbuffer(0), numbytes, 
numneeded, numprinters) 






















































































If retval = 0 ' failed again! 
Debug.Print "Could not successfully enumerate the printes." 
End ' abort program 
End If 
End If 
' Convert longbuffer() data into printinfo() 
ReDim printinfo(0 To numprinters - 1) As PRINTER INFO 2 ' room for each printer 
For c = 0 To numprinters - 1 ' loop, putting each set of information into each 
element 
' longbuffer(21 * c) = .pServerName, longbuffer(21 * c + 1) = .pPrinterName, etc. 











' For each string, the string is first buffered to provide enough room, and then 
the string is copied. 

' For each structure, the memory of it is directly copied via CopyMemory using the 
pointer. 

printin 








£E 


fo(c).pServerName = Space(lstrlen(longbuffer(21 * c))) 








retval = lstrcpy(printinfo(c).pServerName, longbuffer(21 * c)) 
printinfo(c).pPrinterName = Space (lstrilen(longbuffer(21 * c + 1))) 
retval = lstrcpy(printinfo(c).pPrinterName, longbuffer(21 * c + 1)) 
printinfo(c).pShareName = Space(lstrien(longbuffer(21 * c + 2))) 


retval = lstrcpy(printinfo(c).pShareName, longbuffer(21 * c + 2)) 
printinfo(c).pPortName = Space (lstrlen (longbuffer (21 * c 


















































printinfo(c).pDriverName = Space(lstrlen(longbuffer(21 * 
retval = lstrcpy(printinfo(c).pDriverName, longbuffer (21 
printinfo(c).pComment = Space(lstrlen(longbuffer(21 * c + 5 


retval = lstrcpy(printinfo(c).pComment, longbuffer(21 * c+ 5 
printinfo(c).pLocation = Space(lstrilen(longbuffer(21 * c + 6) 





+ 

retval = lstrc (printinfo(c).pPortName, longbuffer(21 * c 
C 

* 






































retval = lstrc (printinfo(c).pLocation, longbuffer(21 * c + 6)) 
CopyMemory printinfo(c).pDevMode, longbuffer(21 * c + 7), 


£ 



























































Len (printinfo (c) .pDevMode) 
fo(c).pSepFile = Space (lstrlen(longbuffer(21 * c + 8))) 
retval = lstrcpy(printinfo(c).pSepFile, longbuffer(21 * c + 8)) 


£ 


fo(c).pPrintProcessor = Space (lstrlen(longbuffer(21 * c + 9))) 








printin 








printin 








retval = lstrcpy(printinfo(c).pPrintProcessor, longbuffer(21 * c + 9)) 
printinfo(c).pDatatype = Space (lstrlen (longbuffer (21 * c 
retval = lstrcpy(printinfo(c).pDatatype, longbuffer (21 * 
printinfo(c).pParameters = Space(lstrlen(longbuffer(21 * 


£ 


retval = lstrepy (printinf 






















































































* Q0 Q + 





o(c).pParameters, longbuffer (21 
CopyMemory printinfo(c).pSecurityDescriptor, longbuffer (21 
Len (printin 
prřrintini 























(c).pSecurityDescriptor) 
.Attributes = longbuffer(21 * c + 13) 
.Priority = longbuffer(21 * c + 14) 

.DefaultPriority = longbuffer(21 * c + 15) 


.StartTime = longbuffer(21 * c + 16) 


























printini 


























printini 




















printinfo 
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E 


printinfo(c).UntilTime = longbuffer(21 * c + 17) 

printinfo(c).Status = longbuffer(21 * c + 18) 

printinfo(c).cJobs = longbuffer(21 * c + 19) 
(c) 


.AveragePPM = longbuffer(21 * c + 20) 




















printinfo 
Next c 











' Display the name of each printer and its average page per minute (ppm) rate 
For c = 0 To numprinters - 1] 











Debug.Print printinfo(c).pPrinterName; " prints an average of"; 
printinfo(c).AveragePPM; "pages per minute." 
Next c 


Category: Printers 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/e/enumprinters.html 
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EnumPropsEx Function 





Declare Function EnumPropsEx Lib "user32.d11" Alias "EnumPropsExA" (ByVal hWnd As 
Long, ByVal lpEnumFunc As Long, ByVal lParam As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


EnumPropsEx enumerates all of the window properties of a window. Information about each property is passed, one at a 








time, to the specified callback function. The window properties are not enumerated in any particular order. 


Return Value 


If the window had no window properties set, the function returns -1. Otherwise, the function returns whatever the most 
recent value the callback function returned was. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to enumerate the window properties of. 
[pEnumFunc 
A pointer to the PropEnumProcEx callback function which receives information about each enumerated window 
property. 
lParam 
An additional value to pass to the function specified by JpEnumFunc. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' List the names of each window property belonging to window 
' Forml. This example does not display the actual data in the properties 
' because the callback function is not told what the handle for each 

" property refers to. 


' *** Place the following code in a module. *** 
' This callback function merely displays the name of the window property 


' it is given. 

















Public Function PropEnumProcEx (ByVal hwnd As Long, ByVal lpszString As Long, 
hData As Long, ByVal dwData As Long) As Long 

Dim propname As String ' receives the name of the window property 

Dim retval As Long ' generic return value 





' Copy the string pointed to by lpString into a "real" 


propname = Space(lstrlen(lpszString) ) 


retval = lstrcpy(propname, lpszString) 
' Display the property name (not including its value). 








Debug.Print 





"— "; propname 


' Tell EnumPropsEx to continue enumeration. 





PropEnumProcEx = 1 


End Function 


string. 


the properties. 





' *** Place the following code wherever you wish to enumerat 


Dim retval As Long ' result of enumeration 














Debug.Print "BEGINNING ENUMERATION OF Forml's PROPERTIES" 











' Enumerate the properties of window Forml. 


retval = EnumPropsEx (Forml.hWnd, AddressOf PropEnumProcEx, 
If retval = -1 Then ' no properties to enumerate 








Debug.Print 
End If 





Category 


Window Properties 











"(no window properties were found)" 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: December 24, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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ByVal 


http://216.26.168.92/vbapi/ref/e/enumpropsex.html 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/enumpropsex.html 
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EnumThreadWindows Function 








Declare Function EnumThreadWindows Lib "user32.d11" (ByVal dwThreadId As Long, ByVal 
lpfn As Long, ByVal lParam As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


EnumThread Windows enumerates and provides handles to all of the windows owned and controlled by a given thread. 
(Note that these windows include many windows not visible to the user.) Each time a window is located, the function passes 
that handle to an application-defined callback function. The function continues doing so until all windows have been 
enumerated, or until the process has been aborted. 





Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwThreadId 

An identifier to the thread to enumerate the windows of. 
lpfn 

A pointer to the application-defined callback function EnumThreadWndProc. 
lParam 

An additional value to pass to the application-defined callback function. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Display the window title of all windows controlled by the thread 

' which the window Forml is in. This task is given to the callback function, which 
' will receive each handle individually. Note that if the window has no title bar 
' text, it will not be displayed (for clarity's sake). 











' *** Place this code in a module. This is the callback function. *** 
' This function displays the title bar text of the window identified by hwnd. 
Public Function EnumThreadWndProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 





















































Dim slength As Long, wintext As String ' title bar text length and buffer 
Dim retval As Long ' return value 
Static winnum As Integer ' counter keeps track of how many windows have been 
enumerated 
winnum = winnum + 1 ' one more window enumerated.... 
slength = GetWindowTextLength(hwnd) + 1 ' get length of title bar text 
If slength > 1 ' if return value refers to non-empty string 
buffer = Space (slength) " make room in the buffer 
retval = GetWindowText (hwnd, buffer, slength) ' get title bar text 
Debug.Print "Window #"; winnum; " : "; ' display number of enumerated window 
Debug.Print Left (buffer, slength - 1) ' display title bar text of enumerated 
window 
End If 
EnumThreadWndProc = 1 ' return value of 1 means continue enumeration 





End Function 





' *** Place this code wherever you want to enumerate the windows. *** 
Dim threadid As Long, processid As Long ' receive id to thread and process of Forml 
Dim retval As Long ' return value 











' Determine the thread which owns the window Forml. 

threadid = GetWindowThreadProcessId(Forml.hWnd, processid) 

' Use the callback function to list all of th numerated thrad windows. Note that 
lParam 

' is set to 0 because we don't need to pass any additional information to the 


function. 
retval = EnumThreadWindows (threadid, AddressOf EnumThreadWndProc, 0) 























See Also 


EnumChild Windows, EnumWindows 


Category 


Windows 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: August 15, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/enumthreadwindows.html 
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shop.com | 
EnumWindows Function 
Declare Function EnumWindows Lib "user32.dll" (ByVal lpEnumFunc As Long, ByVal 


lParam As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


EnumWindows enumerates and provides handles to all of the currently open top-level windows. This function will ignore 





child windows. (Note that the top-level windows include many windows not visible to the user.) Each time a window is 
located, the function passes that handle to an application-defined callback function. The function continues doing so until all 
windows have been enumerated, or until the process has been aborted. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pEnumFunc 

A pointer to the application-defined callback function Enum WindowsProc. 
lParam 

An additional value to pass to the application-defined callback function. 


Example: 





' Display the title bar text of all top-level windows. This 
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task is given to the callback function, which will receive each handle 
individually. 

' Note that if the window has no title bar text, it will not be displayed (for 
clarity's sake). 








' *** Place this code in a module. This is the callback function. *** 
' This function displays the title bar text of the window identified by hwnd. 
Public Function EnumWindowsProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 





















































Dim slength As Long, buffer As String ' title bar text length and buffer 
Dim retval As Long ' return value 
Static winnum As Integer ' counter keeps track of how many windows have been 
enumerated 
winnum = winnum + 1 ' one more window enumerated.... 
slength = GetWindowTextLength(hwnd) + 1 ' get length of title bar text 
If slength > 1] ' if return value refers to non-empty string 
buffer = Space (slength) ' make room in the buffer 
retval = GetWindowText (hwnd, buffer, slength) ' get title bar text 
Debug.Print "Window #"; winnum; " : "; ' display number of enumerated window 
Debug.Print Left (buffer, slength - 1) ' display title bar text of enumerated 
window 
End If 
EnumWindowsProc = 1] ' return value of 1 means continue enumeration 





End Function 


' xxx Place this code wherever you want to enumerate the windows. *** 




















Dim retval As Long ' return value 

' Use the above callback function to list all of th numerated windows. Note that 
lParam is 

' set to 0 because we don't need to pass any additional information to the function. 
retval = EnumWindows (AddressOf EnumWindowsProc, 0) 





See Also 


EnumChildWindows, EnumThread Windows 





Category 


Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: January 16, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/enumwindows.html 
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EqualRect Function 


Declare Function EqualRect Lib "user32.d11" (lpRectl As RECT, lpRect2 As 
RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


EqualRect determines if two rectangles are equal. Rectangles are considered equal if and only if the upper-left and 
lower-right corners (the points that define the rectangles) of one rectangle are equal to those of another. The 
function returns 1 if the two rectangles are equal and 0 if they are unequal. 


lpRectl 

The first of the two rectangles to check. 
lpRect2 

The second of the two rectangles to check. 


Example: 


Demonstrate equal and unequal rectangles 


















































Dim r As RECT, s AS RECT ' rectangles to use 

Dim areequal As Long ' receives whether the rectangles are equal or not 

Dim retval As Long ' return value 

' Initialize the two rectangles using the API 

retval = SetRect(r, 15, 20, 100, 110) ' r = (15,20)-(100,110) 

retval = SetRect(s, 15, 20, 100, 110) ' s = (15,20)-(100,110) 

areequal = EqualRect(r, s) ' compare the rectangles 

If areequal = 1 Then Debug.Print "Are Equal" Else Debug.Print "Are Not Equal" 


Change the second rectangle 

retval = SetRect(s, 30, 45, 200, 250) ' s = (30,45)—-(200, 250) 

areequal = EqualRect(r, s) ' compare the rectangles 

If areequal = 1 Then Debug.Print "Are Equal" Else Debug.Print "Are Not Equal" 
' The first time is Are Equal, the second is Are Not Equal. 








See Also: CopyRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 


http://216.26.168.92/vbapi/ref/e/equalrect.html (1 of 2) [9/1/2002 5:18:31 PM] 


Windows API Guide: EqualRect Function 


Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 








Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/e/equalrect.html 
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EqualRgn Function 








Declare Function EqualRgn Lib "gdi32.dll1" (ByVal hSrcRgnl As Long, ByVal hSrcRgn2 As 
Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


EqualRgn determines if two regions contain the exact same area. Although the region handles will of course be different, they 
could still refer to regions of identical size, shape, and position. 


Return Value 


If the two regions are equal, the function returns a non-zero value. If the two regions are different, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


hSrcRgn1 

A handle to the first of the two regions to compare. 
hSrcRgn2 

A handle to the second of the two regions to compare. 


Example 


Perform a simple illustration of equal and unequal regions. Besides showing how the function works, there's no practical value 
to this example. The example runs when you click on command button Command 1 in a form window. So, naturally, there has 
to be a command button named Command! on that window. 
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' This code is licensed according to the terms and conditions listed here. 





" Declar 


' (Copy 


Public D 





hSrcRgn2 _ 


D 





Public 


As Long 


Public D 





' xxx P] 


Private 


End Sub 





Categ 


Regions 


ations and such 
them to the 
eclare Function 


As Long) As Lon 
eclare Function 


g 
Create 





(declarations) 
EqualRgn Lib "gdi32.d1l1" ( 





Elliptickgn Lib 


needed for the example: 
section of a module.) 








ByVal hSrcRgnl As Long, ByVal 





"gdi32.dll1" (ByVal nLeftRect As Long, 

















eclare Function 


ByVal nTopRect As Long, 





DeleteObject Lib 





ace the following code inside a form. 


Sub Commandi1_Click () 
Dim hRgnl As Long, 
Dim areequal As Long 
Dim retval As Long 














hRgn2 As Long, 
' receives eg 
' generic ret 






































ByVal nRightRect As Long, 








ByVal nBottomRect As Long) 








"gdi32.dll" (ByVal hObject As Long) As Long 


EER 


hRgn3 As Long ' the three regions 
ual/unequal indicator 


urn value 




















' Define all three regions as elliptical. 

hRgnl = CreateBRllipticRgn(20, 30, 120, 80) 

hRgn2 = CreateEllipticRgn(20, 30, 120, 80) 

hRgn3 = CreateBRllipticRgn(50, 50, 200, 150) 

' Compare regions 1 and 2 (they will be equal). 

areequal = EqualRgn(hRgnl, hRgn2) 

If areequal = 0 Then Debug.Print "Not Equal" Else Debug.Print "Equal" 
' Compare regions 1 and 3 (they will not be equal). 

areequal = EqualRgn(hRgnl, hRgn3) 

If areequal = 0 Then Debug.Print "Not Equal" Else Debug.Print "Equal" 





























' Delete th 

retval = DeleteObject ( 
retval = DeleteObject ( 
retval = DeleteObject ( 














ory 


Go back to the Function listing. 





Go back to the Reference section index. 


Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


hRgn1) 
hRgn2) 
hRgn3) 

















three regions to free up resources. 
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ExitWindowsDialog Function 








Declare Sub ExitWindowsDialog Lib "shell132.d11" Alias "#60" (ByVal hwndOwner As 
Long) 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Unknown. 


The ExitWindowsDialog function is officially undocumented. 


Description & Usage 


ExitWindowsDialog prompts the user with the "Shut Down Windows" dialog box. This is the same box as the one that 
appears when the user selects "Shut Down" from the Start menu. Unfortunately, there is no way to know what the user 
chose in the dialog box, or if the user simply cancelled it. Unlike most API dialogs, this function actually begins the shut 
down, reboot, or whatever other process the user selected. 


Return Value 


This function does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hwndOwner 
A handle to the window that is opening the Shut Down dialog box. 


Example 


This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Sub ExitWindowsDialog Lib "shell132.d11" Alias "#60" (ByVal hwndOwner 


As Long) 














' When the user clicks button Commandl on window Forml, display the 
' Shut Down Windows dialog box. 
Private Sub Command1_Click () 
ExitWindowsDialog Forml.hWnd 
' That's all it takes! 
End Sub 








See Also 
RestartDialog 
Category 


Shell 


Back to the Function list. 
Back to the Reference section. 





Last Modified: July 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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ExitWindowsEx Function 


Declare Function ExitWindowsEx Lib "user32.d1ll1" (ByVal uFlags As Long, 
ByVal dwReserved As Long) As Long 


Platforms: Win 95/98, Win NT 


ExitWindowsEx shuts down or reboots the user's computer. Of course, since the shutdown/reboot 
process will begin once the function is called, there won't normally be much left for your program to do. 
The function returns 0 if an error occured, or 1 if successful. 


uF lags 
One or more of the following flags specifying how to shut down or reboot the computer: 
EW X_FORCE = 4 
Force any applications to quit instead of prompting the user to close them. 
EW X_LOGOFF = 0 
Log off the network. 
EWX_POWEROFF = 8 
Shut down the system and, if possible, turn the computer off. 
EW X_REBOOT = 2 
Perform a full reboot of the system. 
EWX_SHUTDOWN = 1 
Shut down the system. 
dwReserved 
Reserved for future versions of Windows. Always set to 0. 


Example: 


" Reboot the computer, forcing any open programs to close 
Dim retval As Long ' return value 


retval = ExitWindowsEx (EWX_REBOOT Or EWX_FORCE, 0) 
If retval = 0 Then Debug.Print "Reboot attempt failed." 


Category: Other 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/e/exitwindowsex.html 


http://216.26.168.92/vbapi/ref/e/exitwindowsex.html (2 of 2) [9/1/2002 5:18:48 PM] 


Windows API Guide: ExtFloodFill Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





ExtFloodFill Function 


Declare Function ExtFloodFill Lib "gdi32.dll1" (ByVal hdc As Long, ByVal nXStart As 
Long, ByVal nYStart As Long, ByVal crColor As Long, ByVal fuFillType As Long) As 
Long 




















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ExtFloodFill performs a flood fill operation on a device using that device's currently selected brush. The flood fill begins at a 
single point and extends in all directions until a condition is met. The flood fill can extend either until a certain boundary 
color is reached or while a certain color is being filled over. 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 
A handle to a device context to the device to perform the flood fill on. 
nXStart 
The x-coordinate of the point to begin the flood fill at. 
nY Start 
The y-coordinate of the point to begin the flood fill at. 
crColor 
The RGB value of the color determining the extent of the flood fill operation. Its exact interpretation depends on the 
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flag passed as fuFillType. 
juFillType 

One of the following flags specifying how to determine the boundary of the flood fill operation: 

FLOODFILLBORDER 
Fill from the beginning point in all directions until a boundary of color crColor is reached. The flood fill will 
cover over any colors within the region which do not have the color of crColor. 

FLOODFILLSURFACE 
Fill from the beginning point in all directions as long as the fill-in color crColor is encountered. The boundary 
of the flood fill is made up of any color which is not identical to crColor. 


Constant Definitions 


Const FLOODFILLBORDER = 0 
Const FLOODFILLSURFACE = 1 




















Example 


This code is licensed according to the terms and conditions listed here. 


Draw a solid green ellipse on window Forml and fill 
" the area outside of it with a diagonally cross-hatched red brush. 














Dim hPen As Long, hBrush As Long ' handles to the pen and brush to be used 
Dim hOldPen As Long, hOldBrush As Long ' handles to the previously selected objects 
Dim retval As Long ' return value 








Create a solid green pen with a width of one pixel. 
hPen = CreatePen(PS_SOLID, 0, RGB(0, 255, 0O)) 

' Select it for use in Forml, noting the previous pen. 
hOldPen = SelectObject (Forml.hDC, hPen) 

" Create a blue diagonally cross-hatched brush. 

hBrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0, 0, 255)) 
' Select it for use in Forml, noting the previous brush. 
hOldBrush = SelectObject (Forml.hDC, hBrush) 






































' Draw an ellipse with bounding rectangle (100,150)-(350, 250) 
retval = Ellipse(Forml.hDC, 100, 150, 350, 250) 





















































' Flood fill the area outside the ellipse (use a green boundary) 

' starting at the point (25,30) outside the ellipse. 

retval = ExtFloodFill(Forml.hDC, 25, 25, RGB(0, 255, 0), FLOODFILLBORDER) 
' Select the previously selected pen and brush. 

retval = SelectOb ject (Forml.hDC, hOldPen) 

retval = SelectObject (Forml.hDC, hOldBrush) 

' Delete the pen and brush to free up resources. 

retval = DeleteObject (hPen) 

retval = DeleteObject (hBrush) 




















Category 
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Bitmaps 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Extracticon Function 


Declare Function ExtractIcon Lib "shell32.d11" Alias "ExtractIconA" (ByVal 
hInst as Long, ByVal lpszExeFileName As String, ByVal nIconIndex As Long) As 
Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ExtractIcon extracts a single icon from a file. This file can be an executable (.exe) file, a dynamic link library (.dll), 
or an icon file (.ico). Alternately, this function can also determine how many icons are stored in such a file. The icon 
generated by this function must be destroyed using DestroylIcon after the program has finished using it. 


Return Value 


If the function failed because the specified file was not found, the function returns 1. If the function failed because 
the icon requested by the function did not exist, the function returns 0. If the function succeeded and the number of 
icons in the file was requested, the function returns the number of icons stored in the file. If the function succeeded 
and an icon was specified, the function returns a handle to the extracted icon. 


Visual Basic-Specific Issues 


None. 


Parameters 


hInst 
A handle to the instance of the application calling the function. 
lpszExe FileName 
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The name of an .exe, .dll, or .ico to extract an icon from. 

nIconIndex 
If this is -1, the function returns the number of icons stored in the specified file. If this is a non-negative 
number, the function extracts the icon using this value as the zero-based index (an index of 0 identifies the 
first icon, etc.). Windows 95, 98, NT 4.0 or later, 2000: If this is negative and not -1, the function extracts 
the icon whose resource identifier equals the absolute value of this parameter. (To extract an icon with a 
resource identifier of 1, ExtractlconEx must be used instead.) 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Display the first icon (index 0) stored in the executable file 

" C:\MyApp\Prog.exe on window Forml. The icon must be destroyed after the 
' program finishes using it. 

Dim hIcon As Long ' handle to the function gotten from the executable file 
Dim retval As Long ' return value 








' Extract the first icon stored in the aforementioned executable file. 
hIcon = ExtractIcon(App.hInstance, "C:\MyApp\Prog.exe", 0) 

' Only attempt to display the icon if we successfully extracted it. 

If hIcon = 0 Then 








Debug.Print "Failed to extract the icon -- aborting." 
End ' terminate the program 
Else 
' Display the icon at coordinates (100, 75) on window Forml. 


retval = Drawlcon(Forml.hDC, 100, 75, hIcon) 
' Although the icon's image is still visible, the icon itself is not in use. 
' Therefore we destroy it to free up resources. 
retval = Destroylicon (hIcon) 
End If 

















See Also 


ExtractIconEx 


Category 


Icons 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


http://216.26.168.92/vbapi/ref/e/extracticon.html (2 of 3) [9/1/2002 5:19:04 PM] 


Windows API Guide: ExtractIcon Function 


Last Modified: August 4, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www. vbapi.com/ref/e/extracticon. html 


http://216.26.168.92/vbapi/ref/e/extracticon.html (3 of 3) [9/1/2002 5:19:04 PM] 


Windows API Guide: ExtractIconEx Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 





shop.com | 
ExtractlconEx Function 
Declare Function ExtractIconEx Lib "Shell132.dl11" Alias "ExtractIconExA" (ByVal 





























lpszFile As String, ByVal nIconIndex As Long, phiconLarge As Long, phiconSmall As 
Long, ByVal nIcons As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


ExtractIconEx extracts multiple icons from a file. This file can be an executable file (.exe), a dynamic link library (.dll), or 
an icon file (.ico). This function can extract both large and small icons, whose handles are placed into two arrays. Optionally, 
this function can also determine how many large/small icon pairs are stores in such a file. Each icon which this function 
extracts must be destroyed using Destroylcon after the program has finished using it. 


Return Value 


If nIconIndex is set to -1, phiconLarge is set to 0, and phiconSmall is set to 0, the function returns the number of icons stored 
in the file specified. Otherwise, the function returns the number of icons successfully extracted from the file. 


Visual Basic-Specific Issues 


When passing 0 explicitly as phiconLarge or phiconSmall, the 0 must be preceeded by the ByVal keyword. See the example 
for a demonstration. 


Parameters 


IpszFile 
The name of the .exe, .dll, or .ico file to extract the icons from. 

nIconIndex 
The zero-based index of the first icon to extract from the file. If this is -1 and both phiconLarge and phiconSmall are 
0, the function returns the number of icons stored in the file. Windows 95, 98, NT 4.0 or later, 2000: If this is a 
negative integer and at least either phiconLarge or phiconSmall (or both) are not zero, the function first extracts the 
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icon whose resource identifier equals the absolute value of this parameter. 

phiconLarge 
An array which receives the handles of the large icons extracted from the file. To not extract any large icons, pass 0 as 
this parameter. 

phiconSmall 
An array which receives the handles of the small icons extracted from the file. To not extract any small icons, pass 0 
as this parameter. 

nicons 
The number of icons to extract from the file. Icons are extracted sequentially, beginning with the icon identified by 
nIconIndex. 


Example 


This code is licensed according to the terms and conditions listed here. 





' Extract all of the regular-sized icons from the file 

' C:\MyApp\Prog.exe. Display them in a row, stretching or shrinking them to 
' a width of 32 and a height of 64. Note how dynamically allocated arrays 

' are used to receive the icon handles. Draw all icons on a light-gray 
background on the window Forml. 




















Dim hIcons() As Long ' dynamic array to receive handles to the icons 
Dim numicons As Long ' number of regular icons in the file 

Dim hBrush As Long ' handle to the background brush to use 

Dim c As Long ' counter variable 

Dim retval As Long ' return value 














' Determine how many regular icons exist in the file and resize 


the array accordingly. 
numicons = ExtractIconEx("C:\MyApp\Prog.exe", -1, ByVal 0, ByVal 0, 0) 
If numicons = 0 Then 














Debug.Print "No icons found in the file -- aborting." 

End * abort the program if failure occurs 
End If 
ReDim hIcons(0 To numicons - 1) As Long ' resize the array to hold all the handles 
' Get a handle to the stock solid light gray brush to use for the background. 
hBrush = GetStockOb ject (LTGRAY_BRUSH) ' handle to the brush 


Extract all of the icons to display. 
retval = ExtractIconEx("C:\MyApp\Prog.exe", numicons, hIcons (0), ByVal 0, 0) 


Loop through each icon, displaying it as previously mentioned. 





























For c = 0 To numicons =- 
' The x coordinate equals 32 * c. The y coordinate is always 0. 
' Display this particular icon. 
retval = DrawlconEx(Forml.hDC, 32 * c, 0, hIcons (c), 32, 64, O0, hBrush, DI_NORMAL) 
' Now destroy this icon since we no longer are using it. 
retval = DestroyltIcon(hIcons (c) ) 
Next c 


See Also 
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ExtractIcon 
Category 


Icons 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FileTimeToLocalFileTime Function 
Declare Function FileTimeToLocalFileTime Lib "kernel32.d11" (lpFileTime As 














FILETIME, lpLocalFileTime As FILETIME) As Long 
Platforms: Win32s, Win 95/98, Win NT 


FileTimeToLocalFileTime converts a time from UTC time (also known as Greenwich Mean Time) to "local time" 
(inside the computer's selected time zone). The source and target times are stored in FILETIME structures. The function 


returns | if successful, or 0 if an error occurs. 


lpFileTime 
The source time and date, which are in UTC time. 
[pLocalFileTime 
Receives the time and date stored in /pFileTime converted into the computer's current time zone time. 





























Example: 

' Search for all files that match "C:\MyProgram\user*.*", Display 

' the creation time of each file. Since the file search functions give the file 
times in UTC 

' time, they must be converted to local time before they are displayed. 

Dim hsearch As Long ' handle to the file search 

Dim findinfo As WIN32 FIND DATA ' receives info about matching files 

Dim success As Long ' will be 1 if successive searches are successful, 0 if not 
Dim localtime As FILETIME ' receives local creation time 

Dim systime As SYSTEMTIME ' receives creation time 

Dim retval As Long ' generic return value 








' Begin a file search: 








hsearch = FindFirstFile("C:\MyProgram\user*.*", findinfo) 
If hsearch = -1 Then ' no files match the search string 
Debug.Print "(no files matched search parameter)" 
End ' abort program 
End If 


T € 


Display creation date of each file that matches the search. Note that the name 
' is displayed, the next file (if any) is found, and then the loop restarts. 
' This way the first file (found above) will also be displayed. 

Do ' begin loop 
' Convert UTC FILETIME to local SYSTEMTIME and display the date: 


£ 


retval = FileTimeToLocalFileTime (findinfo.ftCreationTime, localtime) 
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retval = FileTimeToSystemTime(localtime, systime) 





Debug.Print "Date:"; systime.wMonth; "-"; systime.wDay; "-"; systime.wYear 


' Get the next matching file and loop if it exists: 
success = FindNextFile(hsearch, findinfo) 





Loop Until success = 0 ' keep looping until no more matching files are found 





" Close the file search handle 
retval = FindClose (hsearch) 





See Also: LocalFileTimeToFileTime 
Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FileTimeToSystemTime Function 











Declare Function FileTimeToSystemTime Lib "kernel32.d11" (lpFileTime As FILETIME, 
lpSystemTime As SYSTEMTIME) As Long 























Platforms: Win 32s, Win 95/98, Win NT 


FileTimeToSystemTime converts a time and date stored in a FILETIME structure to an identical time and date stored in a 
SYSTEMTIME structure. The latter structure provides a easier way to access a date and time, whereas the former is used by 
Windows to identify times and dates associated with files. The data put into the SYSTEMTIME structure identifies the same 
time and date as the source structure does. The function returns 0 if an error occured, or 1 if successful. 





[pFileTime 
The date and time, in FILETIME form, to convert. 
lpSystemTime 
Receives the date and time converted into SYSTEMTIME format. 


Example: 





' Display the date when file C:\MyProgram\datafile.txt was 

' created. Note how CreateFile's alternate declare must be used under Win 95/98 -- 

' see that function's page for more information. Also note how the times returned by 
GetFileTime 






















































































' need to be converted so the program can figure out what the date actually is. 
Dim hfile As Long ' receives the handle to the file 

Dim ctime As FILETIME ' receives creation date and time of the file 

Dim atime As FILETIME ' receives last access date and time of the file 

Dim wtime As FILETIME ' receives last write-to date and time of the file 

Dim createtime As SYSTEMTIME ' receives a converted form of ctime 

Dim retval As Long ' return value 




















" Get a handle to the file (note how the alternate declare is used): 
hfile = CreateFileNS ("C:\MyProgram\datafile.txt", GENERIC_READ, FILE_SHARE READ, 0, 
OPEN_EXISTING, FILE _ATTRIBUTE_ ARCHIVE, 0) 
I 





































































































f hfile = -1 Then ' if the file could not be opened 
Debug.Print "Could not open the file C:\MyProgram\datafile.txt." 
End ' abort the program 

End If 











' Get the various times and dates associated with the file: 
retval = GetFileTime(hfile, ctime, atime, wtime) 






































" Convert the creation time from a FILETIME structure to a SYSTEMTIME structure (for 
usability): 
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retval = FileTimeToSystemTime (ctime, createtime) 








Display the creation date of the file: 








Debug.Print "Creation Date:"; createtime.wMonth; "- 





createtime.wYear 


' 


Close the file 


retval = CloseHandle (hfile) 





See Also: SystemTimeToFileTime 
Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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FillMemory Function 
Declare Sub FillMemory Lib "kernel32.d11" Alias "RtlFillMemory" (Destination As 


Any, ByVal Length As Long, ByVal Fill As Byte) 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


FillMemory fills a location in memory with a certain value. The function does this by setting each byte starting at the 
given memory location to the desired value. The memory location is identified by a pointer to the memory address. 


Return Value 


FillMemory does not return a value. 


Visual Basic-Specific Issues 


A pointer to any variable can be automatically generated merely by passing that variable as Destination. However, if 
either a String or a Long holding the desired memory address is passed, the ByVal keyword must preceed it. See the 
example below for a demonstration. 


Parameters 


Destination 

A pointer to the location in memory (often the memory address of a variable) to begin filling with a certain value. 
Length 

The number of memory bytes, beginning with the address identified by Destination, to fill. 
Fill 

The byte value to set each byte in the desired memory location to. 
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Example 


' This code is licensed according to the terms and conditions listed here. 




















' Initialize all the elements in an array of bytes to the value 76. Also 
" set each character in a 20-character string to the character "Xx". 
Dim bytearray(0 To 9) As Byte ' array of 10 bytes 
Dim bytestring As String ' string to fill 
Dim c As Integer ' counter variable 
' Fill the memory at bytearray() in order to initialize its members to 76. 
that, to 
' identify the pointer to bytearray()'s memory, it is passed as normal. 
FillMemory bytearray(0), 10, 76 ' fill 10 bytes to the byte value 76 
' Display the results to verify that it worked. 
For c = 0 To 9 ' loop through each element 
Debug.Print bytearray(c); ' each value displayed will be 76 
Next c 
' Now fill a 20-character string with "X" (using its ASCII code). Note how, 
Visual 
' Basic, the ByVal keyword must preceed the string in this case. 
bytestring = Space (20) ' make the string 20 characters long 
FillMemory ByVal bytestring, 20, Asc("X") ' set the contents to a bunch of 


' Display the results to verify that it worked. 
Debug.Print bytestring ' will be twenty X's 





See Also 


ZeroMemory 


Category 


Memor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: July 25, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/f/fillmemory.html 





http://216.26.168.92/vbapi/ref/f/fillmemory.html (2 of 2) [9/1/2002 5:19:33 PM] 


Note 


in 


my T s 


Windows API Guide: FillRect Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





FillRect Function 


Declare Function FillRect Lib "user32.dll" (ByVal hdc As Long, lpRect As RECT, 
ByVal hBrush As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


FillRect fills a rectangular area on a device using the specified brush. The outline of the rectangular area is not drawn, 
and the bottom and right edges of the given rectangle are not filled in (they are not considered to be part of the interior 
of the rectangle). Note that this function uses the brush passed to the function, so it is not necessary to use SelectObject 
to have the device select the brush first. The function returns 1 if successful, or O if an error occured. 


hdc 

A device context to the device to fill a rectangular area of. 
lpRect 

The coordinates of the rectangular area to fill. 
hBrush 

A handle to the brush to use to fill in the rectangular area. 


Example: 


' Use a blue diagonal-cross hatched brush to fill in a rectangular 


' area on window Forml. The rectangular area has coordinates (20,25)-(200,175). 
Dim hbrush As Long ' receives handle to the blue hatched brush to use 

Dim r As RECT ' rectangular area to fill 

Dim retval As Long ' return value 


' Set the coordinates of the rectangle r 

retval = SetRect(r, 20, 25, 200, 175) ' now r = (20,25)-(200,175) 

' Create a blue diagonal-cross hatched brush 

hbrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0, 0, 255)) 

' Fill in the desired rectangular area 

retval = FillRect (Forml.hDC, r, hbrush) ' fill the rectangle using the brush 
" Delete the brush we created in order to free up resources 

retval = DeleteObject (hbrush) 














See Also: FillRgn, FrameRect 
Category: Filled Shapes 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 
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FillRgn Function 








Declare Function FillRgn Lib "gdi32.d11" (ByVal hdc As Long, ByVal hRgn As Long, 
ByVal hBrush As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


FillRgn fills the area defined by a region on a device. Instead of using the device's currently selected brush, the region is 
filled using a brush passed to the function. The boundary of the region is not drawn; only its area is filled. The function 
returns 0 if an error occured, or a non-zero value if successful. 


hdc 

A device context to the device to fill a region of. 
hRgn 

A handle to the region on the device to fill. 
hBrush 

A handle to the brush to use to fill the region. 


Example: 


' This code is licensed according to the terms and conditions listed here. 


ci 


' Use the light-gray solid stock brush to fill an elliptical region on window 
' Forml. The bounding rectangle of the ellipse is (30,20)-(150,110). 




















Dim hrgn As Long ' handle to the region to fill 
Dim hbrush As Long ' handle to the brush to fill the region with 
Dim retval As Long ' return value 











' First, get a handle to the stock light-gray solid brush. 
hbrush = GetStockObject (LTGRAY_BRUSH) 

" Next, create the elliptical region and get a handle to it. 
hrgn = CreateBllipticRgn(30, 20, 150, 110) 
































' Fill the region using the light-gray brush. 

retval = FillRgn(Forml.hDC, hrgn, hbrush) 

" Delete the region to free resources. The stock brush does not need to be deleted. 
retval = DeleteObject (hrgn) 











See Also: FillRect, FrameRgn 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 
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FindClose Function 
Declare Function FindClose Lib "kernel32.dl11" (ByVal hFindFile As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 
FindClose terminates a file-search operation initiated by FindFirstFile. This function closes the file search handle. 


hFindFile 
The search handle of the file-search operation to end. 









































Example: 

' Search for all files that match "C:\MyProgram\user*.*". Display 

' the filename of each file that matches the string. 

Dim hsearch As Long ' handle to the file search 

Dim findinfo As WIN32 FIND DATA ' receives info about matching files 

Dim success As Long ' will be 1 if successive searches are successful, 0 if not 
Dim buffer As Long ' string buffer to use to process the filename (s) 

Dim retval As Long ' generic return value 


Begin a file search: 
hsearch = FindFirstFile("C:\MyProgram\user*.*", findinfo) 











If hsearch = -1 Then ' no files match the search string 
Debug.Print "(no files matched search parameter)" 

End ' abort program 
End If 














' Display name of each file that matches the search. Note that the name is 
displayed, the 
" next file (if any) is found, and then the loop restarts. This way the first file 
' (found above) will also be displayed. 
Do ' begin loop 
' Extract the filename from the fixed-length string: 
buffer = Left (findinfo.cFileName, InStr(findinfo.cFileName, vbNullChar) - 1) 
Debug.Print buffer ' display this filename 


























' Get the next matching file and loop if it exists: 
success = FindNextFile(hsearch, findinfo) 











Loop Until success = 0 ' keep looping until no more matching files are found 


" Close the file search handle 
retval = FindClose (hsearch) 
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See Also: FindFirstFile, FindNextFile 
Category: Files 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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FindFirstFile Function 


Declare Function FindFirstFile Lib "kernel32.d11" Alias "FindFirstFileA" (ByVal 
lpFileName As String, lpFindFileData As WIN32 FIND DATA) As Long 









































Platforms: Win 32s, Win 95/98, Win NT 


FindFirstFile begins a file search and provides information about the first matching file. The function searches for files 
based only on a filename with wildcards (* or ?). The search only looks in a single directory for the file(s), but it will 
identify any directory names in that directory that match the search string. Identifying information about the file is put into 
the variable passed as /pFindFileData. The function returns a "search handle" which can be used to look for additional 
matching files (via FindNextFile), or -1 if no files match the search (or if an error occured). 


lpFileName 

The file search string to look for, including the complete path. It can contain the wildcards * or ?. 
[pFindFileData 

Receives identifying information about the first file that matches the search string. 
































Example: 

' Search for all files that match "C:\MyProgram\user*.*". Display 

' the filename of each file that matches the string. 

Dim hsearch As Long ' handle to the file search 

Dim findinfo As WIN32 FIND DATA ' receives info about matching files 

Dim success As Long ' will be 1 if successive searches are successful, 0 if not 
Dim buffer As Long ' string buffer to use to process the filename (s) 

Dim retval As Long ' generic return value 











' Begin a file search: 
hsearch = FindFirstFile("C:\MyProgram\user*.*", findinfo) 
If hsearch = -1 Then ' no files match the search string 
Debug.Print "(no files matched search parameter)" 

End ' abort program 
End If 














' Display name of each file that matches the search. Note that the name is 
displayed, the 
" next file (if any) is found, and then the loop restarts. This way the first file 
' (found above) will also be displayed. 
Do ' begin loop 
' Extract the filename from the fixed-length string: 
buffer = Left (findinfo.cFileName, InStr(findinfo.cFileName, vbNullChar) - 1) 
Debug.Print buffer ' display this filename 
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' Get the next matching file and loop if it exists: 
success = FindNextFile(hsearch, findinfo) 








Loop Until success = 0 ' keep looping until no more matching files are found 





" Close the file search handle 
retval = FindClose (hsearch) 








See Also: FindClose, FindNextFile 
Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FindNextFile Function 








Declare Function FindNextFile Lib "kernel32.dl11" Alias "FindNextFileA" (ByVal 
hFindFile As Long, lpFindFileData As WIN32 FIND DATA) As Long 


























Platforms: Win 32s, Win 95/98, Win NT 


FindNextFile continues a file search began by FindFirstFile. It finds and provides identifying information about the next 
file that matches the search string. This information is put into the variable passed as [pFindFileData. The function returns 1 
if another matching file was found, or 0 if no more matching files exist (or if an error occured). 


hFindFile 
The handle to the file search initiated by FindFirstFile. 
lpFindFileData 
Receives identifying information about the next matching file that was found. 
































Example: 

' Search for all files that match "C:\MyProgram\user*.*". Display 

' the filename of each file that matches the string. 

Dim hsearch As Long ' handle to the file search 

Dim findinfo As WIN32 FIND DATA ' receives info about matching files 

Dim success As Long ' will be 1 if successive searches are successful, 0 if not 
Dim buffer As Long ' string buffer to use to process the filename (s) 

Dim retval As Long ' generic return value 











Begin a file search: 
hsearch = FindFirstFile("C:\MyProgram\user*.*", findinfo) 

















If hsearch = -1 Then ' no files match the search string 
Debug.Print "(no files matched search parameter)" 
End ' abort program 

End If 








Display name of each file that matches the search. Note that the name is 
displayed, the 
" next file (if any) is found, and then the loop restarts. This way the first file 
' (found above) will also be displayed. 
Do ' begin loop 
' Extract the filename from the fixed-length string: 
buffer = Left (findinfo.cFileName, InStr(findinfo.cFileName, vbNullChar) - 1) 
Debug.Print buffer ' display this filename 





























' Get the next matching file and loop if it exists: 
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success = FindNextFile(hsearch, findinfo) 
Loop Until success = 0 ' keep looping until no more matching files are found 





" Close the file search handle 
retval = FindClose (hsearch) 











See Also: FindClose, FindFirstFile 
Category: Files 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FindWindow Function 


Declare Function FindWindow Lib "user32.d11" Alias "FindWindowA" (ByVal 
lpClassName As String, ByVal lpWindowName As String) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Find Window searches all windows for one which matches the window class name and/or window name. The 
function's searching mechanism is not case-sensitive. If you do not wish to specify one of the parameters, pass a null 
string for it. 


Return Value 


If successful, the function returns a handle to the window that was found. If no matching window could be found, or if 
an error occured, the function returns zero (use GetLastError to get the error code). 


Visual Basic-Specific Issues 


To pass a null string as one of the function's parameters, use the vbNullString constant. 


Parameters 


lpClassName 

The name of the window class of the window to find. To ignore the window's class, specify a null string. 
lpWindowName 

The name of the title bar text of the window to find. To ignore the window's text, specify a null string. 


Example 
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Search for a window called Minesweeper and flash its title bar once. We don't need to know the name of the window's 
class to find it, since most likely there won't be any unless Windows's Minesweeper game is running. This is all done 
when the user clicks button cmdFind, so to use this example, you naturally must place a command button named 
cmdFind on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function FindWindow Lib "user32.d11" Alias "FindWindowA" (ByVal 
lpClassName As String, 
ByVal lpWindowName As String) As Long 

Public Declare Function FlashWindow Lib "user32.dl1" (ByVal hWnd As Long, ByVal 
bInvert As Long) As Long 
Public Declare Sub Sleep Lib "kernel32.d11" (ByVal dwMilliseconds As Long) 











' *** Place the following code inside a form. *** 


Private Sub cmdFind_Click () 
Dim hWnd As Long ' receives handle to the found window 
Dim retval As Long ' generic return value 


' Attempt to locate a window titled Minesweeper. 
hWnd = FindWindow(vbNullString, "Minesweeper") 
If hWnd = O Then 
Debug.Print "Minesweeper is not currently running." 








Else 
' Flash the window's title bar on and off once. 
retval = FlashWindow (hWnd, 1) 
Sleep 500 ' pause for half a second 
retval = FlashWindow (hWnd, 0) 
End If 


End Sub 


See Also 


FindWindowEx 


Category 


Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FindWindowEx Function 














Declare Function FindWindowEx Lib "user32.dl11" Alias "FindWindowExA" (ByVal 
hwndParent As Long, ByVal hwndChildAfter As Long, ByVal lpszClass As String, ByVal 
lpszWindow As String) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Find Window Ex searches for a window matching a specified window class name and/or window name. The function 
searches all of the child windows of a given window (if desired), beginning with the windows below a specified child 
window. To ignore the window's class and/or title, pass a null string for those parameters. 


Return Value 


If successful, the function returns a handle to the found window. If no matching window could be found, or if an error 
occured, the function returns zero (use GetLastError to get the error code. 





Visual Basic-Specific Issues 


To pass a null string as one of the function's parameters, use the vbNullString constant. 


Parameters 


hWndParentA handle to the parent window to search the child windows of. To search all windows, specify 0 for this 
parameter. 
hWndChildAfterA handle to the child window specifying a place to begin searching. Searching begins with the child window 
immediately after this window in the Z-order. If this is 0, searching begins with the child window at the top of the Z-order. 
IpszClass 

The name of the window class of the window to find. Specify a null string to ignore the class. 
IpszWindow 

The name of the title bar text of the window to find. Specify a null string to ignore the window's title. 
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Example 


Display the name of the first command button on window Form1. The buttons on a form are child windows of the window 
they appear in. In VB5 and VB6, buttons created in the Form Editor have class "ThunderCommandButton". This search runs 
when the user clicks button cmdFind, so to use this example, you must first place a command button named cmdFind on a 
form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function FindWindowEx Lib "user32.dll1" Alias "FindWindowExA" (ByVal 
hwndParent As Long, _ 

ByVal hwndChildAfter As Long, ByVal lpszClass As String, ByVal lpszWindow As 
String) As Long 
Public Declare Function GetWindowTextLength Lib "user32.d11" Alias 
"GetWindowTextLengthA" _ 

(ByVal hWnd As Long) As Long 
Public Declare Function GetWindowText Lib "user32.d1l1" Alias "GetWindowTextA" (ByVal 
hWnd As Long, _ 

ByVal lpString As String, ByVal nMaxCount As Long) As Long 









































' *** Place the following code inside the form window. *** 


Private Sub cmdFind_Click () 











Dim hWnd As Long ' handle to the found window (the command button) 
Dim slength As Long ' length of the found window's text 

Dim wintext As String ' holds the window's text 

Dim retval As Long ' return value 

' Find the "topmost" command button on Forml. Begin searching at the top. 


hWnd = FindWindowEx (Forml.hWnd, 0, "ThunderCommandButton", vbNullString) 
If hWnd = 0 Then 
Debug.Print "No command buttons of class ThunderCommandButton were 














found." 
Else 
' Get the text displayed in the button. 
slength = GetWindowTextLength (hWnd) 
wintext = Space(slength + 1) 
retval = GetWindowText (hWnd, wintext, slength + 1) 
' Remove the terminating null and display the result. 
wintext = Left (wintext, slength) 
Debug.Print "The command button's name is: "; wintext 
End If 
End Sub 


See Also 


FindWindow 
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FlashWindow Function 


Declare Function FlashWindow Lib "user32.d1l1" (ByVal hwnd As Long, ByVal 
bInvert As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


Flash Window flashes a window one step. Flashing is where the title bar of the window is switched from an 
active to inactive look (or vice versa) to get the user's attention. Normally this is done multiple times, 
instead of just once. When you are done flashing, be sure to call the function again, this time with b/nvert 
set to 0. The function returns 0 if the window's look was inactive before flashing, or 1 if its look was active. 


hwnd 
The handle of the window to flash one step. 

bInvert 
Specifies how to flash. If non-zero, switches the title bar from an active to inactive look (or vice 
versa). If zero, restores the window to its normal look. 


Example: 


' Flash Forml five times to get the user's attention 


Dim c As Integer, retval As Long ' counter variable & return value 

For c = 1 To 10 ' flash on five times, off five times 
retval = FlashWindow (Forml.hWnd, 1) ' toggle the look of the window 
Sleep 500 ' halt execution for 500 milliseconds (1/2 minute) 

Next c 

retval = FlashWindow(Forml.hWnd, 0) ' make sure the window looks normal 


Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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FrameRect Function 


Declare Function FrameRect Lib "user32.dl1" (ByVal hdc As Long, lpRect As RECT, 
ByVal hBrush As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


FrameRect draws a one-pixel-wide frame around a rectangle on a device using a given brush. This frame is equivalent to 
what the edge of a filled rectangle (using FillRect) would be. Note that this function uses the brush passed to the function, 


so it is not necessary to use SelectObject to have the device select the brush first. The function returns 1 if successful, or 0 
if an error occured. 


hdc 

A device context to the device to draw the rectangular frame on. 
IpRect 

The rectangle that defines the rectangular frame to draw. 
hBrush 

A handle to the brush to use to draw the rectangular frame. 


Example: 


' Use a blue diagonal-cross hatched brush to draw a rectangular 








' frame on window Forml. The rectangular frame has coordinates (20,25)-(200,175). 
Dim hbrush As Long ' receives handle to the blue hatched brush to use 

Dim r As RECT ' rectangular area to frame 

Dim retval As Long ' return value 





' Set the coordinates of the rectangle r 

retval = SetRect(r, 20, 25, 200, 175) ' now r = (20,25)-(200,175) 
" Create a blue diagonal-cross hatched brush 

hbrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0O, 0, 255)) 



































' Fill in the desired rectangular area 

retval = FrameRect (Forml.hDC, r, hbrush) ' frame the rectangle using the brush 
" Delete the brush we created in order to free up resources 

retval = DeleteObject (hbrush) 














See Also: FillRect, FrameRgn 
Category: Filled Shapes 





Go back to the alphabetical Function listing. 
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FrameRgn Function 
Declare Function FrameRgn Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal hRgn As Long, 








ByVal hBrush As Long, ByVal nWidth As Long, ByVal nHeight As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


FrameRgn draws a frame (border) around a given region on a device using the specified brush. The device's currently 
selected brush is not used. The width and height of the drawn frame are also specified by the function. The function 
returns 0 if an error occured, or a non-zero value if successful. 


hdc 
A device context to the device to draw on. 
hRgn 
A handle to the region to draw the frame of. 
hBrush 
A handle to the brush to use to draw the frame. 
nWidth 
The width in pixels of vertical brush strokes to use to draw the frame. 
nHeight 
The height in pixels of horizontal brush strokes to use to draw the frame. 


Example: 





' Draw a frame around an elliptical region on window Forml. The frame will 

' have a width of 5 and a height of 3. The region has bounding rectangle (20, 30)- 
(220,180). 

' A green diagonally cross-hatched brush is used. 








Dim hRgn As Long ' handle to the region to frame 
Dim hBrush As Long ' handle to the green diagonally cross-hatched brush 
Dim retval As Long ' generic return value 


" Create the elliptical region and the brush. 
hRgn = CreateEllipticRgn(20, 30, 220, 180) ' elliptical region 
hBrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0, 255, 0)) " brush 
































' Frame the region using the created brush. 


retval = FrameRgn(Forml.hDC, hRgn, hBrush, 5, 3) ' frame width = 5, height = 3 








' Delete the region and brush to free up resources. 
retval = DeleteObject (hRgn) 
retval = DeleteOb ject (hBrush) 
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GetActiveWindow Function 


Declare Function GetActiveWindow Lib "user32.d11" () As Long 

Platforms: Win 32s, Win 95/98, Win NT 

GetActiveWindow returns a handle to your program's currently active window. This only works with windows 
created by your application -- in other words, it won't find the active window of other programs. If your program 
is in the background, the function will get the window that would be active if the program were active. If an error 
occurs, or if there is no active window to your program, the function instead returns 0. 


Example: 


' Use FlashWindow to flash the title bar of the program's 
' currently active window once. 


Dim hactive As Long ' handle to the active window 
Dim retval As Long ' return value 
hactive = GetActiveWindow () ' get the handle of the program's active window 


' The next three lines flash the window's title bar 
retval = FlashWindow(hactive, 1): Sleep 250 





retval FlashWindow(hactive, 1): Sleep 250 


FlashWindow (hactive, 0) 





retval 





See Also: GetForegroundWindow, GetWindow, SetActiveWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetArcDirection Function 


Declare Function GetArcDirection Lib "gdi32.dl1l1" (ByVal hdc As Long) 
Platforms: Win 32s, Win 95/98, Win NT 


GetArcDirection determines the direction in which arcs are drawn on a graphics-capable device. Arcs 
can be drawn either clockwise or counterclockwise from the starting point to the ending point. Although 
this function is supported in Win 95/98, that platform ignores the setting and always draws arcs 
counterclockwise! The function returns 0 if an error occured, or exactly one of the following flags 
specifying which direction arcs on the device will be drawn: 


AD_CLOCKWISE = 2 

Arcs are drawn clockwise from the starting point to the ending point. 
AD_COUNTERCLOCKWISE = 1 

Arcs are drawn counterclockwise from the starting point to the ending point. 


hdc 
The device context of the device to find the arc-drawing direction of. 


Example: 


' Display which direction window Forml draws arcs. 
Dim arcdir As Long ' receives arc direction 


arcdir = GetArcDirection (Forml1.hDC) " get the arc direction for Formi 
If arcdir = AD_CLOCKWISE Then 
Debug.Print "Forml draws arcs clockwise." 
ElseIf arcdir = AD_COUNTERCLOCKWISE Then 
Debug.Print "Forml draws arcs counterclockwise." 
End If 


See Also: AngleArc, Arc, ArcTo, SetArcDirection 
Category: Lines & Curves 
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GetAsyncKeyState Function 








Declare Function GetAsyncKeyState Lib "user32.dll1" (ByVal vKey As Long) As Integer 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetAsyncKeyState determines whether a certain key is currently pressed and whether that key has been pressed since the 
last call to the function. This function fails if the thread calling it does not currently have the input focus. 


Return Value 


If the function fails (if the current thread does not have the input focus), the function returns 0. If the &H8000 bit of the 
return value is set, the key has been pressed at least once since the last time the thread called GetAsyncKeyState. If the 
&H1 bit of the return value is set, the key is currently pressed down. 


Visual Basic-Specific Issues 


None. 


Parameters 


vKey 
The virtual-key code of the key to check. Windows NT, 2000: This could also be one of the following flags which 
distinguish between the left and right Ctrl, Alt, and Shift keys: 
VK_LSHIFT 
The left Shift key. 
VK_RSHIFT 
The right Shift key. 
VK_LCONTROL 
The left Ctrl key. 
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VK_RCONTROL 

The right Ctrl key. 
VK_LMENU 

The left Alt key. 
VK_RMENU 

The right Alt key. 


Constant Definitions 


Const VK_LSHIFT = &HAO 
Const VK_RSHIFT = &HA1 
Con VK_LCONTROL = &HA2 
Const VK_RCONTROL = &HA3 
Const VK_LMENU = &HA4 
Const VK_RMENU = &HA5 





n 


ct ct 








Example 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function GetAsyncKeyState Lib "user32.dl11" (ByVal vKey As Long) As 
Integer 














' Determine whether the Q key has been pressed or not since the last 
' call to the function (assuming this example code has already been run earlier). 
' The code runs when button Commandl is pressed. 





Private Sub Command1_Click () 
Dim keystate As Integer ' state of the Q key 








' Get the state of the Q key as returned by the function. 

' (vbKeyQ is a VB-defined constant for Q's virtual-key code) 

keystate = GetAsyncKeyState (vbKeyQ) 

' Check the &H8000 bit of the return value. 

If keystate And &H8000 Then 

Debug.Print "The Q key has been pressed since the last check." 








Else 





Debug.Print "The Q key has not been pressed since the last check." 
End If 
End Sub 





See Also 


GetKeyState 
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Category 


Keyboard 
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GetBrushOrgEx Function 


Declare Function GetBrushOrgEx Lib "gdi32.d11" (ByVal hdc As Long, 
lpPoint As POINT TYPE) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GetBrushOrgEx determines the origin point for using a brush on a given device is. All brushes are stored 
as an 8x8 pixel block, but Windows can offset the "origin" point determining the adjustment of the brush 
fill is. For example, an origin of (2,3) would shift the fill pattern design 2 pixels right and 3 pixels down. 
The current brush origin is put into the variable passed as /pPoint. The function returns 1 if successful, or 0 
if an error occured. 


hdc 

A device context to the device to find the brush origin point of. 
lpPoint 

Receives the (x,y) coordinate pair of the device's brush origin point. 


Example: 


' Display the brush origin point for window Forml. 
Dim brushorg As POINT TYPE ' receives brush origin point 





Dim retval As Long ' return value 


' Determine the brush origin and display its coordinates: 

retval = GetBrushOrgEx (Forml.hDC, brushorg) 

Debug.Print "All brush designs are offset"; brushorg.x; "pixels right "; 
Debug.Print "and"; brushorg.y; "pixels downward." 


See Also: SetBrushOrgEx 
Category: Brushes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetCapture Function 


Declare Function GetCapture Lib "user32.d11" () As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetCapture identifies which window currently has captured the mouse input, if any. However, this function only works if a 
window owned by the calling thread; if another program's window has captured the mouse, this function will not work. 





Return Value 


If a window owned by the calling thread has captured the mouse, the function returns a handle to that window. If no thread 
window has captured the mouse, the function returns 0. 





Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Constant Definitions 


Example 


If a window owned by the program has captured the mouse input, display its caption. If not, inform the user that no program 
window has captured the mouse. The capture is checked when the user clicks button Command1. To use this example, you 
must first place a command button named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 









































' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetCapture Lib "user32.d1l1" () As Long 
Public Declare Function GetWindowText Lib "user32.dl1" Alias "GetWindowTextA" (ByVal 
hWnd _ 
As Long, ByVal lpString As String, ByVal nMaxCount As Long) As Long 
Public Declare Function GetWindowTextLength Lib "user32.dl11" Alias 
"GetWindowTextLengthA" _ 
(ByVal hWnd As Long) As Long 
' *** Place the following code inside a form window. *** 
Private Sub Command1_Click () 
Dim hWndCapture As Long ' handle to the window that captured the mouse 
Dim wintext As String ' receives the text of the capturing window 
Dim slength As Long ' the length of that string 








' First, see if a thread window has even captured the mouse. 
hWndCapture = GetCapture () 


If hwndCapture = 0 Then 
Debug.Print "This program has not captured the mouse." 








Else 

' Get the capturing window's text and display it. 
slength = GetWindowTextLength(hWndCapture) + 1 
wintext = Space(slength) 
slength = GetWindowText (hnWndCapture, wintext, slength) 
wintext = Left (wintext, slength) 














captured the mouse." 
End If 
End Sub 


See Also 
ReleaseCapture, SetCapture 


Category 


Mouse 


Back to the Function list. 
Back to the Reference section. 
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GetClassIinfo Function 


Declare Function GetClassInfo Lib "user32.d1l1" Alias "GetClassInfoA" (ByVal 
hInstance As Long, ByVal lpClassName As String, lpWndClass As WNDCLASS) As Long 


Platforms 


e Windows 95: Supported but Obsolete; use GetClassInfoEx instead. 

e Windows 98: Supported but Obsolete; use GetClassInfoEx instead. 

e Windows NT: Requires Windows NT 3.1 or later but Obsolete in Windows NT 3.5 or later; use 
GetClassInfoEx instead. 

e Windows 2000: Supported but Obsolete; use GetClassInfoEx instead. 

e Windows CE: Requires Windows CE 1.0 or later. 











Description & Usage 


GetClassInfo retrieves most of the information associated with a window class. The information is placed into the 
structure passed as [pWndClass. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hInstance 
A handle to the instance which owns the window class, or 0 if the window class is defined by the operating 
system. 

lpClassName 
The name of the window class to retrieve information about. 

lpWndClass 
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Receives the information about the window class. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Draw the icon and cursor from the window class to which window 
' Forml belongs. The two images are drawn on Forml. 

Dim classinfo As WNDCLASS ' receives the class information 

Dim classname As String ' receives the name of the window class 
Dim slength As Long ' the length of the window class's name 

Dim retval As Long ' return value 


' First, get the name of the window class to which Formi belongs. 
classname = Space (255) ' make enough room in the buffer 
slength = GetClassName(Forml.hWnd, classname, 255) ' get the name 





classname = Left(classname, slength) ' remove the empty space 


' Get the information about the window class. Since this is a Visual Basic- 
' generated window, its window class belongs to the application. 
retval = GetClassInfo(App.hInstance, classname, classinfo) 


' Now draw the window class's icon and cursor on window Forml. 

' Draw the icon. 

retval = DrawlconEx(Forml.hDC, 0, 0, classinfo.hIcon, 0, 0, 0, 0, DI_NORMAL) 

' Draw the cursor. If it's animated, draw only the first frame of it. 

retval = DrawīIconEx(Form1.hDC, 50, 0, classinfo.hCursor, 0, 0, 0, 0, DI_NORMAL) 








See Also 


GetClassInfoEx, GetClassLong 


Category 


Window Classes 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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GetClassIinfoEx Function 


Declare Function GetClassInfoEx Lib "user32.d1ll1" Alias "GetClassInfoExA" (ByVal 
hinst As Long, ByVal lpszClass As String, lpwcx As WNDCLASSEX) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetClassInfoEx retrieves all of the information associated with a window class. The information is placed into the 
structure passed as /pwcx. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hinst 
A handle to the instance which owns the window class, or 0 if the window class is defined by the operating 
system. 
IpszClass 
The name of the window class to retrieve information about. 
lpwcx 
Receives the information about the window class. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Draw the regular icon and small icon from the window class to which 
' window Forml belongs. The two icons are drawn on Forml. 
Dim classinfo As WNDCLASSEX ' receives the class information 





Dim classname As String ' receives the name of the window class 
Dim slength As Long ' the length of the window class's name 
Dim retval As Long ' return value 


' First, get the name of the window class to which Forml belongs. 
classname = Space (255) ' make enough room in the buffer 
slength = GetClassName(Forml.hWnd, classname, 255) ' get the name 





classname = Left(classname, slength) ' remove the empty space 


' Get the information about the window class. Since this is a Visual Basic- 
' generated window, its window class belongs to the application. 
retval = GetClassInfoEx (App.hInstance, classname, classinfo) 


' Now draw the window class's regular and small icons on window Forml. 

' Draw the regular icon. 

retval = DrawlconEx(Forml.hDC, 0, 0, classinfo.hIcon, 0, 0, 0, 0, DI_NORMAL) 

' Draw the small icon. 

retval = DrawlconEx(Forml.hDC, 50, 0, classinfo.hIconSm, 0, 0, 0, 0, DI_NORMAL) 











See Also 


GetClassInfo, GetClassLong 





Category 


Window Classes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetClassLong Function 


Declare Function GetClassLong Lib "user32.d11" Alias "GetClassLongA" (ByVal hWnd 
As Long, ByVal niIndex As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetClassLong retrieves a single 32-bit value from the information about the window class to which the specified window 


belongs. The class's properties may not necessarily match perfectly with the actual properties of the window. This function 
can also retrieve a 32-bit value from the extra memory area associated with the window class. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
desired 32-bit value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to a window which belongs to the class to read a property of. 

nIndex 
To retrieve a 32-bit value from the class's extra memory, set this to the zero-based offset of the byte to begin 
reading at. Valid values are 0 to the number of bytes of extra memory minus 4, inclusive. To retrieve a 32-bit 
property of the class, set this to one of the following flags specifying which 32-bit value to retrieve from the 
window class: 
GCW_ATOM 
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Retrieve the atom which identifies the window class. 
GCL_CBCLSEXTRA 

Retrieve the size in bytes of the extra memory associated with the window class. 
GCL_CBWNDEXTRA 

Retrieve the size in bytes of the extra memory associated with each window belonging to the window class. 
GCL_HBRBACKGROUND 

Retrieve a handle to the brush used to paint the backgrounds of windows belonging to the class. 
GCL_HCURSOR 

Retrieve a handle to the cursor associated with the class. 
GCL_HICON 

Retrieve a handle to the icon associated with the class. 
GCL_HICONSM 

Retrieve a handle to the small icon associated with the class. 
GCL_HMODULE 

Retrieve a handle to the module which registered the class. 
GCL_MENUNAME 

Retrieve a pointer to the string identifying the name of the menu resource associated with the class. 
GCL_STYLE 

Retrieve the window styles associated with the class. 
GCL_WNDPROC 

Retrieve a pointer to the WindowProc hook function which acts as the window procedure for windows 

belonging to the window class. 


Constant Definitions 



































Const GCW_ATOM = -32 

Const GCL_CBCLSEXTRA = -20 
Const GCL_CBWNDEXTRA = -18 
Const GCL_HBRBACKGROUND = -10 
Const GCL_HCURSOR = -12 
Const GCL_HICON = -14 
Const GCL_HMODULE = -1 
Const GCL_MENUNAME = -8 
Const GCL_STYLE = -26 
Const GCL_WNDPROC = -24 
Example 


When the user clicks button Command1, draw the icon associated with the parent form window's class in the corner of the 
client area. This might not be the icon actually displayed by the window. Naturally, to use this exampe, you must first 
place a command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function GetClassLong Lib "user32.dl11" Alias "GetClassLongA" (ByVal 
hWnd As Long, 
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ByVal niIndex As Long) As Long 
Public Const GCL_HICON = -14 
Public Declare Function DrawlIcon Lib "user32.dl1" (ByVal HDC As Long, ByVal x As 





























Long, ByVal y _ 
As Long, ByVal hIcon As Long) As Long 





' Place the following code inside a form window. *** 


Private Sub Commandi_Click () 
Dim hIcon As Long ' handle to the class's icon 
Dim retval As Long ' return value 











' Retrieve a handle to the class's icon. 

hIcon = GetClassLong (Me.hWnd, GCL_HICON) 

' Draw that icon at coordinate (0,0) on Forml. 
retval = Drawlcon(Me.hDC, 0, 0, hIcon) 


End Sub 


























See Also 
GetWindowLong, SetClassLong 
Category 

Window Classes 


Go back to the Function listing. 
Go back to the Reference section index. 





Last Modified: October 29, 2000 
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GetClassName Function 


Declare Function GetClassName Lib "user32.d11" Alias "GetClassNameA" 
(ByVal hWnd As Long, ByVal lpClassName As String, ByVal nMaxCount As Long) 
As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetClassName retrieves the name of the window class to which a window belongs. The name of the class is 
placed into the string passed as lpClassName. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns the number of characters copied into the string passed as /JpClassName. 


Visual Basic-Specific Issues 
None. 


Parameters 


hWnd 
A handle to the window to get the name of the window class of. 


lpClassName 
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A string which receives the name of the window class. This must first be initialized to a sufficient 
length to receive the string. 

nMaxCount 
The size in bytes of the string passed as IpClassName. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Display the name of the window class to which window Forml belongs. 
Dim classname As String ' receives the name of the class 
Dim slength As Long ' length of the string retrieved 











' Make room in the string to receive the information. 

classname Space (255) ' much more than enough room 

' Get the name of the window class. 

slength = GetClassName (Form1.hWnd, classname, 255) 

' Extract the useful information from the string and display it. 
classname = Left (classname, slength) ' remove empty space 
Debug.Print "Forml's window class is: "; classname 


Category 


Window Classes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetClipCursor Function 


Declare Function GetClipCursor Lib "user32.d1ll1" (lprce As RECT) As Long 
Platforms: Win 32s, Win 95/98, Win NT 

GetClipCursor finds the current confinement rectangle of the mouse cursor. The mouse cursor is 
confined by using ClipCursor. The cursor is confined inside this rectangle -- even SetCursorPos cannot 
free it. If there is no apparent confinement rectangle, it is actually the size of the screen. The coordinates 
of the rectangle is put into /prc. The function returns 0 if an error occured, or 1 if it succeeded. 
IprcReceives the coordinates of the confinement rectangle. 


Example: 


' Display the coordinates of the confinement rectangle. 


Dim r AS RECT ' receives coordinates of rectangle 

Dim retval As Long ' return value 

retval = GetClipCursor (r) ' read the coordinates and put them into r 
Debug.Print r.Left; r.Top ' display upper-left (x,y) pair 
Debug.Print r.Right; r.Bottom ' display lower-right (x,y) pair 


See Also: ClipCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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GetComputerName Function 


Declare Function GetComputerName Lib "kernel32.dl1" Alias "GetComputerNameA" 
(ByVal lpBuffer As String, nSize As Long) As Long 


Platforms: Win 95/98, Win NT 


GetComputerName reads the name of the user's computer. The name is put into the string variable passed as lpBuffer. 
The function returns 0 if an error occured or 1 if successful. 


lpBuffer 

A string large enough to hold the returned computer name terminated by a null character. 
nSize 

The length in characters of lpBuffer. 


Example: 


' Display the computer's name 


Dim compname As String, retval As Long ' string to use as buffer & return value 
compname = Space (255) ' set a large enough buffer for the computer name 

retval = GetComputerName (compname, 255) ' get the computer's name 

' Remove the trailing null character from the strong 

compname = Left (compname, InStr(compname, vbNullChar) - 1) 

Debug.Print compname ' display name 


Category: System Information 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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GetCurrencyFormat Function 


Declare Function GetCurrencyFormat Lib "kernel32.d1l1" Alias "GetCurrencyFormatA" 
(ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat As 
Any, ByVal lpCurrencyStr As String, ByVal cchCurrency As Long) As Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetCurrencyFormat formats a currency value for display. By default, the function formats the currency according to the 
specified locale's settings. However, custom formatting preferences can instead be used. The end result of 
GetCurrencyFormat is a currency amount displayed according to the user's preferences. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
number of characters copied into the string passed as JpNumberStr, not including the terminating null character. 


Visual Basic-Specific Issues 


When passing 0 for the /pFormat parameter, the expression ByVal CLng(0) must be used. See the example code for a 
demonstration of this. 


Parameters 


Locale 
The locale identifier of the locale to format the currency value according to. This identifier could be generated by the 
MAKELCID macro. Alternatively, this could be one of the following flags specifying a locale: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
The user's default locale. 
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dwFlags 
If no structure is passed as /pFormat, this parameter determines the settings used to format the currency value. If this 
is 0, the current locale settings are used. Or, this could be the following flag: 
LOCALE_NOUSEROVERRIDE 
Use the system's default settings for the locale, regardless of any modifications the user may have made to it. 
lpValue 
A string containing the number to format. The only allowable characters in this string are the digits 0-9 and at most a 
single decimal point character (.). If the number is negative, the first character in the string must be a minus sign 
character (-). Any other characters are invalid. Notice how you must not include a currency symbol! 
[pFormat 
To override the locale's formatting settings, pass a CURRENCYFMT structure that contains the appropriate 
formatting information. To use the locale's settings instead, pass 0 for this parameter. 
IpCurrencyStr 
String that receives the null-terminated formatted currency string. This string must have enough room to receive the 
string. 
cchCurrency 
The number of characters in the string passed as /pCurrencyStr. 





Constant Definitions 


Const LOCALE _SYSTEM_DEFAULT = &H400 
Const LOCALE _USER_DEFAULT = &H800 
Const LOCALE_NOUSEROVERRIDE = &H80000000 
































Example 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type CURRENCYFMT 
NumDigits As Long 
LeadingZero As Long 
Grouping As Long 
lpDecimalSep As String 
lpThousandSep As String 
NegativeOrder As Long 
PositiveOrder As Long 
lpCurrencySymbol As String 
End Type 
Public Declare Function GetCurrencyFormat Lib "kernel32.d1l1" Alias 
"GetCurrencyFormatA" _ 
(ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, 
lpFormat _ 


As Any, ByVal lpCurrencyStr As String, ByVal cchCurrency As Long) As Long 
Const LOCALE_USER_DEFAULT = &H800 





















































Display the amount of $1,234,567.89 according to two formatting rules. 
' 1. Use the format specified by the current user locale. 
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' 2. Use a custom format specified by a structure passed to the function. 








Dim cft As CURRENCYFMT " custom formatting settings 
Dim formatted As String ' receives the formatted number strings 
Dim strlen As Long ' the length of the formatted string 





' Display the value formatted according to the current locale. 

formatted = Space (256) 

strlen = GetCurrencyFormat (LOCALE _USER_DEFAULT, 0, "1234567.89", ByVal CLng(0), _ 
formatted, Len(formatted) ) 

formatted = Left (formatted, strlen) 

Debug.Print "User locale format: "; formatted 

















' Now display according the format we specify below. 
With cft 
' Display three digits after the decimal point (like in US gasoline prices). 
-NumDigits = 3 
' Display zeros after the decimal point. 
.LeadingZero = 1 
' Group every three digits to the left of the decimal. 
-Grouping = 3 
' Use a comma to as the decimal point (like they do in France and Spain). 









































.lpDecimalSep = "," 
' Likewise, use a period as the grouping separator. 
.lpThousandSep = "." 
' For negative values, place it in parentheses and put the $ sign after the 
digits. 
-.NegativeOrder = 4 
' For positive values, place the $ sign after the digits. 
-PositiveOrder = 1] 
' Use the $ sign to represent the currency. 
.lpCurrencySymbol = "$" 
End With 


formatted = Space (256) 

strlen = GetCurrencyFormat (LOCALE_USER_DEFAULT, 0, "-1234567.89", cft, formatted, 
Len (formatted) ) 

formatted = Left (formatted, strlen) 


£ 


Debug.Print "Custom format: "; formatted 














See Also 


GetNumberFormat 


Category 


National Language Support 





Back to the Function list. 
Back to the Reference section. 








http://216.26.168.92/vbapi/ref/g/getcurrencyformat.html (3 of 4) [9/1/2002 5:21:46 PM] 


Windows API Guide: GetCurrencyFormat Function 


Last Modified: April 16, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/g/getcurrencyformat.html 


http://216.26.168.92/vbapi/ref/g/getcurrencyformat.html (4 of 4) [9/1/2002 5:21:46 PM] 


Windows API Guide: GetCursor Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








GetCursor Function 


Declare Function GetCursor Lib "user32.d11" () As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GetCursor finds the handle to the mouse cursor currently in use. This is the cursor that is being used to 
represent the mouse pointer on the screen. The function returns a handle to the cursor picture if 
successful, or returns 0 if an error occurs. 


Example: 


' Display the hourglass for three seconds, then restore 

" the mouse cursor to whatever it was originally. 

Dim holdcursor As Long ' receives handle to the original cursor 

Dim hcursor As Long ' receives handle to the hourglass (wait) cursor 
Dim retval As Long ' throw-away return value 


holdcursor = GetCursor () " get the handle of the current mouse cursor 
hcursor = LoadCursor(0, IDC_WAIT) " load the hourglass cursor 





retval = SetCursor (hcursor) " set the cursor to the hourglass 





Sleep 3000 ' wait for three seconds 
retval = SetCursor (holdcursor) ' restore the original cursor 





See Also: SetCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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GetCursorPos Function 


Declare Function GetCursorPos Lib "user32.dl1" (lpPoint As POINT TYPE) 
As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GetCursorPos reads the current position of the mouse cursor. The x and y coordinates of the cursor 
(relative to the screen) are put into the variable passed as /pPoint. The function returns 0 if an error 
occured or | if it is successful. 


lpPoint 
Receives the x and y coordinates of the mouse cursor. 


Example: 


' Display the coordinates of the mouse cursor 





Dim coord As POINT TYPE " receives coordinates of cursor 
Dim retval As Long ' return value 
retval = GetCursorPos (coord) " read cursor location 


Debug.Print "The mouse is at:"; coord.x; coord.y 


See Also: SetCursorPos 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
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GetDateFormat Function 


Declare Function GetDateFormat Lib "kernel32.d11" Alias "GetDateFormatA" (ByVal 
Locale As Long, ByVal dwFlags As Long, lpDate As SYSTEMTIME, ByVal lpFormat As 


Any, ByVal lpDateStr As String, ByVal cchDate As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetDateFormat formats a string to display a date according to a locale's settings. The date can be formatted using 
either a predefined format or a custom format specified in the parameter list. The string generated by this function can 
be used to present a more human-readable way to display a date. 





Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
size in bytes of the string placed into the variable passed as /pDateStr. 


Visual Basic-Specific Issues 


When passing 0 for the /pFormat parameter, the expression CLng(0) must be used. 


Parameters 


Locale 
The identifier of the locale to use to format the string as necessary. If this is 0, the locale of the calling thread is 
used. This can also be one of the following flags specifying a default locale: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
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The user's default locale. 
dwFlags 
A combination of the following flags specifying how to format the date string. If a format string is passed as 
IpFormat, this parameter must be set to 0. 
LOCALE_NOUSEROVERRIDE 
Use the system's default date format for the specified locale, ignoring any changes to those defaults 
which the user may have selected. 
LOCALE_USE_CP_ACP 
Use the system's ANSI code page for string translation instead of the locale's code page. 
DATE_SHORTDATE 
Format the date string using the short date format. 
DATE_LONGDATE 
Format the date string using the long date format. 
DATE_YEARMONTH 
Format the date string using the year/month date format. 
DATE_USE_ALT_CALENDAR 
If an alternate calendar exists, use the default date format of that calendar to format the date string. 
DATE_LTRREADING 
Add marks for left-to-right reading layout. 
DATE_RTLREADING 
Add marks for right-to-left reading layout. 
lpDate 
The date to format as a string. The members of the structure which specify the time are ignored. 
lpFormat 
The format template string used to generate the date string. To use one of the predefined formats, this parameter 
must be 0. In a format template string, the following series of characters stand for the following components of 


the date: 
d 

The day of the month as digits without a leading zero for single-digit days. 
dd 

The day of the month as digits with a leading zero for single-digit days. 
ddd 


The three-letter abbreviation for the name of the day of the week. 
dddd 

The full name of the day of the week. 
M 
The month as digits without a leading zero for single-digit months. 
MM 
The month as digits with a leading zero for single-digit months. 
MMM 
The three-letter abbreviation for the name of the month. 
MMMM 

The full name of the month. 





y 
The last two digits of the year without a leading zero for years between ??00-??09. 


yy 
The last two digits of the year with a leading zero for years between ??00-??09. 


yyyy 
All four digits of the year. 
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88 
The period/era string, if defined for the locale. If it is not defined, this string is ignored. 


Any spaces appearing in the template string appear verbatim in the formatted string. To place any other "fixed" 
characters or text in the format string, you must enclose the literal text in single quotation marks. 
lpDateStr 
Receives the formatted date string. This must initally be sufficiently long to receive the string. 
cchDate 
The length of the string passed as /pDateStr. 


Constant Definitions 


Const LOCALE_SYSTEM_DEFAULT = &H400 
Const LOCALE_USER_DEFAULT = &H800 

Const LOCALE_NOUSEROVERRIDE = &H80000000 
Const LOCALE_USE_CP_ACP = &H40000000 
Const DATE_SHORTDATE = &H1 

Const DATE_LONGDATE = &H2 

Const DATE_USE_ALT_CALENDAR = &H4 

Const DATE_YEARMONTH = &H8 

Const DATE_LTRREADING = &H10 

Const DATE_RTLREADING = &H20 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Display today's date first in the default Long Date format and 
' then in the standard HTTP date format. 








Dim today As SYSTEMTIME ' today's date and time 
Dim datestr As String ' receives the formatted date string 
Dim strlen As Long ' length of the buffer for the formatted date string 





' Get today's date and time in the local time zone. 
GetLocalTime today 








' Make sufficient room in the buffer to receive the date string. 

datestr = Space (255) 

' Format today's date as a Long Date. 

strlen = GetDateFormat (0, DATE_LONGDATE, today, CLng(0), datestr, Len(datestr) ) 
' Remove the empty space from the formatted date string. 

datestr = Left(datestr, strlen) 

' Display today's date as a Long Date. 

Debug.Print "Today is "; datestr 





' Now make sufficient room once again. 
datestr = Space (255) 
' Format today's date in the format used in HTTP. 
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strlen = GetDateFormat (0, 0, today, "ddd',' dd MMM yyyy", datestr, Len(datestr) ) 
' Remove the empty space from the formatted string. 

datestr = Left(datestr, strlen) 

' Display today's date in the HTTP-style format. 

Debug.Print "Today is "; datestr 





See Also 
GetTimeFormat 
Category 


National Language Support 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


Last Modified: January 1, 2000 
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GetDC Function 


Declare Function GetDC Lib "user32.dl1" (ByVal hWnd As Long) As Long 











Platforms: Win 32s, Win 95/98, Win NT 


GetDC returns the device context (DC) of a window or other device, given the object's handle. When you are finished using 
the device context, you should use ReleaseDC to free up system resources. If you try to get the device context of something 
that is not a device (i.e., pass the function a handle to a file) or another error occurs, the function will instead return 0. Do not 
use DeleteDC to destroy the device context when you are done. 


hWnd 
The handle of the object or device to get the device context of. 


Example: 


' Find the device context of the desktop 

Dim deskhwnd As Long ' handle to the desktop 

Dim deskhdc As Long ' device context to the desktop 
Dim retval As Long ' return value 














deskhwnd = GetDesktopWindow () " get the desktop's handle 
deskhdc = GetDC (deskhwnd) ' get the desktop's device context 


" You could put any code that works with the desktop here 





retval = ReleaseDC (deskhwnd, deskhdc) ' free up resources associated with the device 





context 


See Also: CreateDC, ReleaseDC 
Category: Devices 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetDesktopWindow Function 
Declare Function GetDesktopWindow Lib "user32.d1l1" () As Long 








Platforms: Win 32s, Win 95/98, Win NT 


GetDesktop Window returns a handle to the desktop window. The desktop window is the window that makes up the desktop 
of the computer -- that is, the screen. If the function fails, it will return O instead of the handle. 


Example: 








' Find the device context of the desktop 

' The handle to the desktop is needed to find the device context 
Dim deskhwnd As Long ' handle to the desktop 

Dim deskhdc As Long ' device context to the desktop 

Dim retval As Long ' return value 














deskhwnd = GetDesktopWindow () ' get the desktop's handle 
deskhdc = GetDC (deskhwnd) ' get the desktop's device context 








' You could put any code that works with the desktop here 





retval = ReleaseDC (deskhwnd, deskhdc) ' free up resources associated with the device 





context 
Category: Windows 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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GetDiskFreeSpace Function 


Declare Function GetDiskFreeSpace Lib "kernel32.d11" Alias 
"GetDiskFreeSpaceA" (ByVal lpRootPathName As String, lpSectorsPerCluster As 
Long, lpBytesPerSector As Long, lpNumberOfFreeClusters As Long, 
lpTotalNumberOfClusters As Long) As Long 








Platforms 


e Windows 95: Supported but Obsolete with OEM Service Release 2 (OEM2) or later; use 
GetDiskFreeSpaceEx instead. 

e Windows 98: Supported but Obsolete; use GetDiskFreeSpaceEx instead. 

e Windows NT: Requires Windows NT 3.1 or later but obsolete in Windows NT 4.0 or later; use 
GetDiskFreeSpaceEx instead. 

e Windows 2000: Supported but Obsolete; use GetDiskFreeSpaceEx instead. 

e Windows CE: Not Supported. 











Description & Usage 


GetDiskFreeSpace retrives information about the amount of space on a disk. This information includes the 
number of sectors in each cluster, the number of bytes in each sector, the number of free clusters, and the total 
number of clusters. Due to the limitations of the 32-bit integer data type, this function only works properly with 
disks with a capacity less than 2 MB. The replacement function GetDiskFreeSpaceEx does not have this limitation. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to determine the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 


None 


Parameters 
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lpRootPathName 
The root directory of the disk to get information on, such as "c:\" or "a:\" 
lpSectorsPerCluster 
32-bit integer variable which receives the number of sectors in a cluster on the disk. 
lpBytesPerSector 
32-bit integer variable which receives the number of bytes in a sector on the disk. 
lpNumberOfF ree Clusters 
32-bit integer variable which receives the number of unused, empty clusters on the disk. Windows 2000: 
This may be lower than the actual value if per-user quotas are enabled. 
lpTotalNumberOfClusters 
32-bit integer variable which receives the total number of clusters, used and unused, on the disk. Windows 
2000: This may be lower than the actual value if per-user quotas are enabled. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Calculate and display the free and total space on drive C: 
Dim secPerClus As Long ' receives sectors per cluster 

Dim bytePerSec As Long ' receives bytes per sector 

Dim freeClus As Long ' receives number of free clusters 
Dim totalClus As Long ' receives total number of clusters 
Dim retval As Long ' return value 








' Read the information into the variables 
retval = GetDiskFreeSpace("c:\", secPerClus, bytePerSec, freeClus, totalClus) 


' Display the information 
Debug.Print "Free space:"; freeClus * secPerClus * bytePerSec; "bytes" 
Debug.Print "Total space:"; totalClus * secPerClus * bytePerSec; "bytes" 





See Also 
GetDiskFreeS paceEx 
Category 
Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetDiskFreeSpaceEx Function 


Declare Function GetDiskFreeSpaceEx Lib "kernel32.d1l1" Alias "GetDiskFreeSpaceExA" 
(ByVal lpDirectoryName As String, lpFreeBytesAvailableToCaller As ULARGE INTEGER, 
lpTotalNumberOfBytes As ULARGE INTEGER, lpTotalNumberOfFreeBytes As ULARGE INTEGER) 
As Long 












































Platforms 


Windows 95: Requires OEM Service Release 2 (OSR2) or later. 
Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 

Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetDiskFreeSpaceEx determines information about the size of a disk. It finds the free space available to the current user, the 
total disk space, and the amount of free space (all in bytes). Each value is placed into a ULARGE_INTEGER structure which 
can hold the unsigned 64-bit integer values. (If your programming language supplies an intrinsic unsigned 64-bit integer data 
type, that can be used instead.) 








Return Value 


If an error occured, the function returns 0 (use GetLastError to retrieve the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pDirectoryName 
The name of a directory on the disk to retrieve the size information about. While this can be the name of the disk's 
root directory, it doesn't have to be. 

IpFreeBytesAvailableToCaller 
Unsigned 64-bit integer variable which receives the amount of free disk space available, in bytes, to the user. 
Windows 2000: This may be lower than the actual value if per-user disk space quotas are enabled. 
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lpTotalNumberOfBytes 


Unsigned 64-bit integer variable which receives the amount of total disk space, in bytes. Windows 2000: This may be 
lower than the actual value if per-user disk space quotas are enabled. 
lpTotalNumberOfFreeBytes 


Unsigned 64-bit integer variable which receives the amount of free disk space, in bytes. 
Example 


Display the total free space available on drive C:. Because Visual Basic doesn't have good support for the 64-bit integers 
needed for modern hard drive's free spaces, the workaround described on this page is needed to display the values properly. 


This example runs when the user click button Command1, so to use this example, you need to place a command button 
named Command! on a form window. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type ULARGE INTEGER 

LowPart As Long 

HighPart As Long 
End Type 
Public Declare Function GetDiskFreeSpaceEx Lib "kernel32.dll1" Alias 
"GetDiskFreeSpaceExA" (ByVal _ 


lpDirectoryName As String, lpFreeBytesAvailableToCaller As ULARGE INTEGER, 


lpTotalNumberOfBytes As ULARGE INTEGER, lpTotalNumberOfFreeBytes As 
ULARGE INTEGER) As Long 


Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 







































































' *** Place the following code inside the form window. *** 





Private Sub Command1_Click () 
































Dim userbytes As ULARGE INTEGER " bytes free to user 

Dim totalbytes As ULARGE INTEGER ' total bytes on disk 

Dim freebytes As ULARGE INTEGER ' free bytes on disk 

Dim tempval As Currency ' display buffer for 64-bit values 
Dim retval As Long ' generic return value 








Get information about the C: drive. 

retval = GetDiskFreeSpaceEx("C:\", userbytes, totalbytes, freebytes) 

' Copy freebytes into the Currency data type. 

CopyMemory tempval, freebytes, 8 

' Multiply by 10,000 to move Visual Basic's decimal point to the end of the 
actual number. 

tempval = tempval * 10000 

' Display the amount of free space on C:. 


Debug.Print "Free Space on the C: drive:"; tempval; "bytes" 
End Sub 
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See Also 
GetDiskFreeSpace 
Category 
Files 


Go back to the Function listing. 
Go back to the Reference section index. 








Last Modified: September 24, 2000 
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GetDoubleClickTime Function 


Declare Function GetDoubleClickTime Lib "user32.d1l1" () As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GetDoubleClickTime determines the maximum time allowed between successive mouse clicks for Windows to 
interpret it as a double click (along with negligible mouse movement). The maximum time between clicks is given in 
milliseconds. The function returns the maximum double click time. 


Example: 


' Display the maximum amount of time between clicks to 
" consider the operation a double click. 
Dim doubletime As Long ' receives double click time 


doubletime = GetDoubleClickTime () ' get the maximum double click time 
Debug.Print doubletime; "milliseconds are allowed between clicks during a double 
click.” 


See Also: SetDoubleClickTime 
Category: Mouse 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetDriveType Function 


Declare Function GetDriveType Lib "kernel32.d11" Alias "GetDriveTypeA" (ByVal 
nDrive As String) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetDriveType finds the type of disks a disk drive is/uses. This could be a fixed (hard) drive, a floppy drive, a CD- 
ROM drive, etc. The function returns the drive type. 0 means that an error occured. 1 means that the specified drive 
does not exist. Other return values are one of the following flags identifying the drive type: 


DRIVE_CDROM = 5 
A CD-ROM drive. 
DRIVE_FIXED = 3 
A hard drive. 
DRIVE_RAMDISK = 6 
A RAM disk. 
DRIVE_REMOTE = 4 
A network drive or a drive located on a network server. 
DRIVE_REMOVABLE = 2 
A floppy drive or some other removable-disk drive. 


nDrive 
The root directory of the drive to check, such as "c:\" or "a:\" 


Example: 


' Determine what type of drive D: is 








Dim drivetype As Long ' receives the drive type 

drivetype = GetDriveType ("d:\") ' determine which kind of drive this is 

If drivetype = 1 Then Debug.Print "Drive D:\ does not exist." 

If drivetype = DRIVE_REMOVABLE Then Print "Drive D:\ is a removable-disk drive." 
If drivetype = DRIVE_FIXED Then Print "Drive D:\ is a hard drive." 

If drivetype = DRIVE_CDROM Then Print "Drive D:\ is a CD-ROM drive." 

1 


GCO: 
Category: Files 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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GetEnvironmentVariable Function 


Declare Function GetEnvironmentVariable Lib "kernel32.d11" Alias 
"GetEnvironmentVariableA" (ByVal lpName As String, ByVal lpBuffer As String, ByVal 
nSize As Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetEnvironmentVariable reads the value of one of the computer's environment variables. The value is placed into the string 
buffer passed as the lpBuffer parameter. 


Return Value 


If the specified environment variable does not exist, the function returns zero. If the string passed as lpBuffer was too short to 
receive the environment variable's value, the function returns the necessary minimum buffer length. If successful, the 
function returns the length of the string copied into /pBuffer, not counting the terminating null character. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpName 
The name of the environment variable to read. 
lpBuffer 
Receives the value of the environment variable. This string must be sufficiently long to receive the value copied into 
1t. 
nSize 
The length of the string passed as [pBuffer. 
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Example 


Read the BLASTER environment variable, which contains some information about the Sound Blaster configuration on the 
computer. Typically, this variable is only used by DOS programs, so it isn't very useful for Windows applications. But then 
again, this is just an example of how to use GetEnvironmentVariable. The example runs when button Command 1 is 
clicked, so you must place a command button named Command! on a form window before running this example. 


This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetEnvironmentVariable Lib "kernel32.d11" Alias 
"GetEnvironmentVariableA" (ByVal _ 


lpName As String, ByVal lpBuffer As String, ByVal nSize As Long) As Long 

















' *** Place the following code inside a form window. *** 





Private Sub Command1_Click() 
Dim envvar As String ' receives the value of the environment variable 
Dim slength As Long ' length of the string copied into envvar 








Make enough room in envvar to receive the data. 




















envvar = Space (256) 
' Read the value of the BLASTER environment variable. 
slength = GetEnvironmentVariable("BLASTER", envvar, Len(envvar) ) 
If slength = 0 Then 
Debug.Print "The BLASTER environment variable does not exist on this 
system." 
Else 
' Remove the terminating null and everything following it. 
envvar = Left (envvar, slength) 
Debug.Print "BLASTER = "; envvar 
End If 
End Sub 


See Also 


SetEnvironmentVariable 


Category 
Processes & Threads 


Back to the Function list. 
Back to the Reference section. 
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GetFileAttributes Function 


Declare Function GetFileAttributes Lib "kernel32.d11" Alias 
"GetFileAttributesA" (ByVal lpFileName As String) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetFileAttributes returns the attributes of a file or a directory. Attributes determine such things as read-only 
status, archive status (most files are), hidden status, etc. If the function fails, it will return O. If the file or 
directory cannot be found, it will return -1. Otherwise, the return value will be one or more of the following file 
attribute flags: 


FILE_ATTRIBUTE_ARCHIVE = &H20 

An archive file (which most files are). 
FILE_ATTRIBUTE_COMPRESSED = &H800 

A file residing in a compressed drive or directory. 
FILE_ATTRIBUTE_DIRECTORY = &H10 

A directory instead of a file. 
FILE_ATTRIBUTE_HIDDEN = &H2 

A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL = &H80 

An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY = &H1 

A read-only file. 
FILE_ATTRIBUTE_SYSTEM = &H4 

A system file, used exclusively by the operating system. 


lpFileName 
The full name of the file or directory to check the attributes of, including the full path. 


Example: 


1 


Display the attributes of C:\Files\program.exe 
Dim attribs As Long ' receives file attributes 


attribs = GetFileAttributes ("C:\Files\program.exe") ' read file attributes 
If (attribs And FILE_ATTRIBUTES_ARCHIVE) <> 0 Then Debug.Print "Archive" 
If (attribs And FILE_ATTRIBUTES_HIDDEN) <> 0 Then Debug.Print "Hidden" 
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If (attribs And FILE_ATTRIBUTES_READONLY) <> 0 Then Debug.Print "Read-only" 
CEGC: ges 


See Also: GetFileInformationByHandle, SetFileAttributes 
Category: Files 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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GetFilelnformationByHandle Function 








Declare Function GetFileInformationByHandle Lib "kernel32.dl1" (ByVal hFile As 
Long, lpFileInformation As BY HANDLE FILE INFORMATION) As Long 



































Platforms: Win 32s, Win 95/98, Win NT 


GetFileInformationByHandle determines various information about a file. This information includes the file's attributes; 
its creation, last-access, and last-modified dates and times; the serial number of the disk the file is on; the size of the file; the 
number of links to it in the file system; and the its unique numeric identifier. All of this information is put into the structure 
passed as [pFileInformation. The function returns 0 if an error occured, or 1 if successful. 


hFile 

A handle to the file to get the information of. 
[pFileInformation 

Receives the information (specified above) relating to the file. 


Example: 





' Display the serial number of the disk that file C:\MyProgram\datafile.txt 









































' is on -- in other words, we are finding the serial number of drive C:. Note that 
here we 

' aren't interested in the other information we receive. Also note that the 
alternate declar 

' of CreateFile must be used here since we're using Win 95/98 -- see its page for 
details. 

Dim hfile As Long ' receives the handle to the file 

Dim fileinfo As BY HANDLE FILE INFORMATION ' receives info about the file 

Dim hexstring As String ' will receive the hexadecimal form of the serial number 
Dim retval As Long ' return value 














" Get a handle to the file (note how the alternate declare is used): 
hfile = CreateFileNS ("C:\MyProgram\datafile.txt", GENERIC_READ, FILE_SHARE READ, 0, 
OPEN_EXISTING, FILE ATTRIBUTE ARCHIVE, 0) 


















































If hfile = -1 Then ' if the file could not be opened 
Debug.Print "Could not open the file C:\MyProgram\datafile.txt." 
End ' abort the program 

End If 





' Display the serial number, using hexadecimal: 








retval = GetFileInformationByHandle(hfile, fileinfo) ' read the information 
hexstring = Hex(fileinfo.dwVolumeSerialNumber) " get the hexadecimal value of the 
serial number 
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If Len(hexstring) < 8 Then ' if the string is less than 8 characters, 

hexstring = String("0", 8 - Len(hexstring)) & hexstring ' then right-pad it with 
" 0 "s 
End If 





Debug.Print "The serial number of C: is "; hexstring 





' Close the file: 
retval = CloseHandle 





See Also: GetFileAttributes, GetFileSize, GetFileTime 
Category: Files 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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Declare Function GetFileSize Lib "kernel32.d1ll" (ByVal hFile As Long, lpFileSizeHigh 











As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GetFileSize determines the size of the file. The file size is given in a 64-bit value that is split into two 32-bit values. The high- 
order half is put into the variable passed as [pFileSizeHigh; the low-order half is returned by the function. To get the size, you 
can either put the binary or hexadecimal values of the two variables side-by-side, or use the formula filesize = IpFileSizeHigh * 
2432 + return value. If an error occurs, the function instead returns -1. 


hFile 

A handle to the file to determine the size of. The file must be opened with at least either read-level or write-level access. 
[pFileSizeHigh 

Variable that receives the high-order half of the file size. 




































































Example: 

' Display the file size of "C:\MyProgram\datafile.txt". Note how 

' the alternate declare of the CreateFile function (needed to get the file's handle) 
' must be used -- see that function's page for details. 

Dim hfile As Long ' receives a handle to the file 

Dim loworder As Long, highorder As Long ' receive the low- and high-order halves of 
the file siz 

Dim retval As Long ' return value 

' Get a handle to the file using CreateFile's alternate declare (necessary for non- 

Win NT). 

hfile = CreateFileNS ("C:\MyProgram\datafile.txt", GENERIC_READ, FILE_SHARE READ, 0, 
























































OPEN_EXISTING, FILE _ATTRIBUTE_ARCHIVE, 0) 
If hfile = -1 Then ' error opening the file 

Debug.Print "Could not open file C:\MyProgram\datafile.txt" 
End ' abort the program 

End If 















































' Read and display that file's size in bytes. 

highorder = 0 ' initialize the value for high-order half 
loworder = GetFileSize(hfile, highorder) ' read the file's size 

If highorder = 0 Then ' if there is no high-order part 

Debug.Print "File size:"; loworder; "bytes" ' display the file size 

Else ' if there is a high-order part (file size >= 4.29 GB!) 

' Visual Basic has no 64-bit variables, so we can't display the actual value: 
Debug.Print "File size:"; highorder; "* 2%32 +"; loworder; "bytes (in base-10)" 
' But we can combine the two hex values to give the result in hexadecimal: 
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Debug.Print "File size: "; Hex(highorder); Hex(loworder); " bytes (in hexadecimal)" 
End If 








" Close the file 
retval = CloseHandle (hfile) ' close the handle 





See Also: GetFileInformationB yHandle 
Category: Files 





Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getfilesize.html 
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GetFileTime Function 








Declare Function GetFileTime Lib "kernel32.dll1" (ByVal hFile As Long, lpCreationTime 
As FILETIME, lpLastAccessTime As FILETIME, lpLastWriteTime As FILETIME) As Long 












































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetFileTime determines the times and dates of creation, last access, and last modification (write-to) of a file. Each of these 
times are placed in the corresponding structures passed to the function. All times obtained by the function are in UTC time 
(Coordinated Universal Time, a.k.a. Greenwich Mean Time (GMT)), not in the system's local time. Note that, depending on 
the operating system, the exact resolution of file times may vary -- the file times obtained by the function may not correspond 
to the actual date and time of creation/access/modification simply because the operating system does not store the information 
that precisely. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non-zero 
value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hFile 
A handle to the file to obtain the creation, last access, and last modification times and dates of. The file must have been 
opened with at least read-level access. 
lpCreationTime 
Receives the time and date of when the file was created. 
lpLastAccessTime 
Receives the time and date of when the file was last accessed. 
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IpLastWriteTime 
Receives the time and date of when the file was last written to or modified. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Display the date on which the file C:\MyApp\test.txt was 
' created. Note how the time zone conversion is necessary. 
















































































Dim hFile As Long ' handle to the opened file 

Dim ctime As FILETIME ' receives time of creation 

Dim atime As FILETIME ' receives time of last access 

Dim mtime As FILETIME ' receives time of last modification 
Dim thetime As SYSTEMTIME ' used to manipulate the time 
Dim retval As Long ' return value 














' First, open the file C:\MyApp\test.txt for read-level access. Note the 
' expression necessary to pass 0 as lpSecurityAttributes. 
hFile = CreateFile("C:\MyApp\test.txt", GENERIC_READ, FILE_SHARE READ, ByVal CLng(0), 
OPEN_EXISTING, FILE _ATTRIBUTE_ARCHIVE, 0) 

If hFile = -1 Then 
Debug.Print "Could not open the file successfully -- aborting." 
End ' terminate the program 

End If 














































































































' Next, get the creation, last-access, and last-modification times. 
retval = GetFileTime(hFile, ctime, atime, mtime) 

" Convert the creation time to the local time zone. 

retval = FileTimeToLocalFileTime(ctime, ctime) 

" Convert the FILETIME format to the SYSTEMTIME format. 

retval = FileTimeToSystemTime (ctime, thetime) 















































' Display the date of creation of the file to the user. 
Debug.Print "The file was created on "; thetime.wMonth; "-"; thetime.wDay; "-"; 
thetime.wYear 























" Close the file to free up resources. 
retval = CloseHandle (hFile) 





See Also 


GetFileInformationByHandle, SetFileTime 





Category 
Files 


Go back to the alphabetical Function listing. 
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Go back to the Reference section index. 





Last Modified: October 1, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/¢/getfiletime.html 
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GetFileVersionInfo Function 











Declare Function GetFileVersionInfo Lib "version.dll" Alias "GetFileVersionInfoA" 
(ByVal lptstrFilename As String, ByVal dwHandle As Long, ByVal dwLen As Long, lpData 
As Any) As Long 























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetFileVersionInfo extracts the version information resource stored inside a 32-bit executable-type file. The version 
information resource is a series of bytes that is difficult to read directly. Use the VerQueryValue to retrieve the desired pieces 
of data from the resource. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 


lpstrFilename 
The full path and filename of the file. 
dwHandle 
Reserved -- set to 0. 
dwLen 
The size in bytes of the buffer passed as /pData. 
lpData 
A buffer, such as a byte array, that receives the version information resource of the file. 
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Example 


Display information about the file whose full path and filename is entered into textbox Text1. Display the version number, 
copyright information, and file description when button Command1 is pressed. To use this example, you obviously have to 
enter the filename of a 32-bit executable/DLL/etc. into Text1. Obviously, this example requires that you create a text box 
called Textl and a command button called Command 1. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetFileVersionIinfo Lib "version.dll" Alias 
"GetFileVersionInfoA" 


(ByVal lptstrFilename As String, ByVal dwHandle As Long, ByVal dwLen As Long, 


























lpData As Any) As Long 
Public Declare Function GetFileVersioniInfoSize Lib "version.dll" Alias _ 

















"GetFileVersionInfoSizeA" (ByVal lptstrFilename As String, lpdwHandle As 
Long) As Long 
Public Declare Function VerQueryValue Lib "version.dll" Alias "VerQueryValueA" 
(pBlock _ 
As Any, ByVal lpSubBlock As String, lplpBuffer As Long, puLen As Long) As 























Long 
Public Declare Function Ilstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 

















As Any, ByVal lpString2 As Any) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 














As Any, _ 
Source As Any, ByVal Length As Long) 
Public Type VS FIXEDFILEINFO 
dwSignature As Long 
dwStrucVersion As Long 
dwFileVersionMS As Long 
dwFileVersionLS As Long 
dwProductVersionMS As Long 
dwProductVersionLs As Long 
dwFileFlagsMask As Long 
dwFileFlags As Long 
dwFileOS As Long 
dwFileType As Long 
dwFileSubtype As Long 
dwFileDateMS As Long 
dwFileDateLS As Long 
End Type 
Public Const VFT_APP = 
Public Const VFT_DLL = 
Public Const VFT_DRV = 
Public Const VFT_VXD = 
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' *** Place the following function definitions inside a module. *** 
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' HIWORD and 
Public Functi 


Dim h 





NEXSt 














End Function 
Public Functi 
Dim h 
hexst 








LOWOR 





End Function 


' This nifty 


HIWOR 


LOWORD are API macros defined below. 























on HIWORD (ByVal dwValue As Long) As Long 
exstr As String 

r = Right ("00000000" & Hex(dwValue), 8) 

D = CLng("&H" & Left (hexstr, 4)) 

on LOWORD (ByVal dwValue As Long) As Long 
exstr As String 

r = Right ("00000000" & Hex(dwValue), 8) 

D = ChLng("&H" & Right (hexstr, 4)) 





subroutine swaps two byte values without needing a buí 


















































ffer variable. 








































































































































































































' This technique, which uses Xor, works as long as the two values to be swapped are 
' numeric and of the same data type (here, both Byte). 
Public Sub SwapByte (bytel As Byte, byte2 As Byte) 

bytel = bytel Xor byte2 

byte2 = bytel Xor byte2 

bytel = bytel Xor byte2 
End Sub 
' This function creates a hexadecimal string to represent a number, but it 
' outputs a string of a fixed number of digits. Extra zeros are added to make 
' the string the proper length. The "&H" prefix is not put into the string. 
Public Function FixedHex (ByVal hexval As Long, ByVal nDigits As Long) As String 

FixedHex = Right ("O0000000" & Hex (hexval), nDigits) 
End Function 
' *** Place the following code inside the form that has Commandl and Textl. *** 
Private Sub Command1_Click () 

Dim vffi As VS FIXEDFILEINFO ' version info structure 

Dim buffer() As Byte ' buffer for version info resource 

Dim pData As Long ' pointer to version info data 

Dim nDataLen As Long ' length of info pointed at by pData 

Dim cpl(0 To 3) As Byte ' buffer for code page & language 

Dim cplstr As String ' 8-digit hex string of cpl 

Dim dispstr As String ' string used to display version information 

Dim retval As Long ' generic return value 

' First, get the size of the version info resource. If this function fails, 
then Textl 

' identifies a file that isn't a 32-bit executable/DLL/etc. 

nDataLen = GetFileVersionInfoSize(Textl.Text, pData) 

If nDataLen = 0 Then 

Debug.Print "Not a 32-bit executable!" 
Exit Sub 

End If 

' Make the buffer large enough to hold the version info resource. 

ReDim buffer(0 To nDataLen - 1) As Byte 

' Get the version information resource. 

retval = GetFileVersionInfo (Textl.Text, 0, nDataLen, buffer(0)) 
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' Get a pointer to a structure that holds a bunch of data. 

retval = VerQueryValue (buffer(0), "\", pData, nDataLen) 

' Copy that structure into the one we can access. 

CopyMemory vffi, ByVal pData, nDataLen 

' Display the full version number of the file. 

dispstr = Trim(Str(HIWORD(vffi.dwFileVersionMS))) & "." & _ 
Trim(Str (LOWORD (vffi.dwFileVersionMS))) & "." & _ 
Trim(Str (HIWORD (vffi.dwFileVersionLS))) & "." & _ 
Trim (Str (LOWORD (vff£i.dwFileVersionLs) )) 

Debug.Print "Version Number: "; dispstr 

' Display the type of file it is (1.e., executable, DLL, etc.). 

Select Case vffi.dwFileType 

Case VFT_APP 
dispstr = "Application" 

Case VFT_DLL 
dispstr = "Dynamic Link Library (DLL)" 

Case VFT_DRV 
dispstr = "Device Driver" 

Case VFT_VXD 
dispstr = "Virtual Device Driver" 

Case Else 
dispstr = "Unknown" 

End Select 

Debug.Print "File Type: "; dispstr 

' Before reading any strings out of the resource, we must first determine the 








code page 


and language. 



































The code to get this information follows. 
"\VarFileInfo\Translation", 








Data, 








& FixedHex (cp 


and 














code pag 


to swap the first two bytes, 


p 


the byte array. 


as well as the last two bytes. 


Convert those four bytes into a 8-digit hexadecimal string. 


L(1), 2) & FixedHex(cpl(2), 2) & 





information from the version 
"\StringFileInfo\" 


language to read strings as. 





info resource. 
& cplstr & 











retval = VerQueryValue (buffer(0), 
nDataLen) 
' Copy that informtion into 
CopyMemory cpl(0), ByVal pData, 4 
' It is necessary 
SwapByte cpl(0), cpl(1) 
SwapByte cpl(2), cpl (3) 
T 
cplstr = FixedHex(cpl(0), 2) 
FixedHex (cpl (3), 2) 
' cplstr now represents th 
' Read the copyright 
retval = VerQueryValue (buffer (0), 
"\LegalCopyright", _ 
pData, nDataLen) 














dispstr = Space (nDataLen) 
retval = lstrcpy(dispstr, p 
' Display the result. 











Debug.Print 
' Similarly, 
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"Copyright Info: 
read a description of the 


We 
r 


dispstr 
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Copy that data into a string for display. 


file and display it. 


Windows API Guide: GetFileVersionInfo Function 








retval = VerQueryValue (buffer(0), "\StringFileInfo\" & cplstr & 








"\FileDescription", 

pData, nDatalen) 

dispstr = Space (nDataLen) 

retval = lstrcpy(dispstr, pData) 




















Debug.Print "File Description: "; dispstr 
End Sub 





See Also 


GetFileVersionInfoSize, VerQuery Value 


Category 
Files 


Back to the Function list. 





Back to the Reference section. 


Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getfileversioninfo.html 
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GetFileVersionInfoSize Function 





Declare Function GetFileVersionInfoSize Lib "version.dll" Alias 
"GetFileVersionInfoSizeA" (ByVal lptstrFilename As String, lpdwHandle As Long) As 
Long 




















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetFileVersionInfoSize determines the length of the version information resource stored with a 32-bit executable-type file. 
The actual version information resource is obtained by using GetFileVersionInfo. This function does not work with 16-bit 
executable-type files, nor with files that are not executable at all. 


Return Value 


If successful, the function returns the size in bytes of the file's version information resource. If an error occured, the function 
returns 0 (use GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


lpstrFilename 
The full path and filename of the file. 

lpdwHandle 
Receives a value of 0. Although this parameter is effectively reserved, you must pass a variable to receive this 
meaningless value. 


Example 
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Display information about the file whose full path and filename is entered into textbox Text1. Display the version number, 
copyright information, and file description when button Command! is pressed. To use this example, you obviously have to 
enter the filename of a 32-bit executable/DLL/etc. into Text1. Obviously, this example requires that you create a text box 

called Textl and a command button called Command_1. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed 
' (Copy them to the 
Declare Funct 


Public 


"GetFileVersionl 





(declar 





ations) 


for the example: 
section of a module.) 
tion GetFileVersionInfo Lib 


"version.dll" Alias 








Public 


Long) A 
Public 


(pB] 





ock 








Long 
Public 


Public 
As Any, 


Public Type VS FIX 
dwSignature As Long 





Declare F 


Declare F 


Declare S 














[NEGA 
(ByVal lptst 
lpData As Any) As L 





trFilename As String, 








ByVal dwHandle As Long, ByVal dwLen As Long, 





ong 





s Long 





As Any, 





As Any, 








Source As Any, 


unction VerQueryVal 


Declare Function GetFileVersionInfoSize Lib 


"GetFileVersionInfoSizeA" (ByVal 


Alias _ 
lpdwHandle As 


"version.dlılı" 
lptstrFilename As String, 











ByVal lpSubl 


unction lstrcpy Lib 








G 


(DEF TLE TINE 














O 





dwStrucVersion As Long 
dwFileVersionMS As 
dwFileVersionLS As 





dwProduct 





dwProduct 


tVersionMS 
tVersionLs 


dwFileFlagsMask As 


dwFileFlags As Long 


dwFileOS As Long 









































Long 
Long 
As Long 
As Long 
Long 


dwFileType As Long 
dwFileSubtype As Long 
dwFileDateMS As Long 
dwFileDateLS As Long 
End Type 
Public Const VFT_APP = &H1 
Public Const VFT_DLL = &H2 
Public Const VFT_DRV = &H3 
Public Const VFT_VXD = &H5 


' ***x Place the following 


' HIWORI 


Public F 








D and LOWORD are API 
unction HIWORD ( 
Dim hexstr As String 


E 








unction de 


macros de 











ue Lib 


Block As String, 


"kernel32.d11" 


ByVal lpString2 As Any) 
ub CopyMemory Lib "kernel32.dl11" Alias 


"version.dll" Alias "VerQueryValueA" 











lplpBuffer As Long, puLen As Long) As 





Alias 





"IstrcpyA" (ByVal lpStringl 





As Long 





"RtlMoveMemory" (Destination 





E 





ByVal dwValue As Long) 


ByVal Length As Long) 


initions inside a module. *** 


ined below. 
As Long 
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End Func 
Public F 





' This nifty subro 
' This technique, 

' numeric and of t 
Public Sub SwapByte 


End Sub 



































hexstr = Right ("O0000000" & Hex(dwValue), 8) 
HIWORD = CLlng("&H" & Left(hexstr, 4)) 

tion 

unction LOWORD (ByVal dwValue As Long) As Long 
Dim hexstr As String 

hexstr = Right ("O0000000" & Hex(dwValue), 8) 
LOWORD = CLng("&H" & Right (hexstr, 4)) 


by 
by 
by 


End Function 

























































































he same data type 

(bytel As Byte, 
tel = bytel Xor byte2 
te2 = bytel Xor byte2 
tel = bytel Xor byte2 





















































utine swaps two byte values wi 
which uses Xor, 


(here, 
byte2 As 











thout needing a buffer variable. 





works as long as the two values to be swapped are 
bo 





th Byte). 
Byte) 




























































































This function creates a hexadecimal string to represent a number, but it 
' outputs a string of a fixed number of digits. Extra zeros are added to make 
' the string the proper length. The "&H" prefix is not put into the string. 
Public Function FixedHex (ByVal hexval As Long, ByVal nDigits As Long) As String 
FixedHex = Right ("O0000000" & Hex(hexval), nDigits) 
End Function 
' ***x Place the following code inside the form that has Commandl and Textl. *** 
Private Sub Command1_Click () 
Dim vffi As VS FIXEDFILEINFO ' version info structure 
Dim buffer() As Byte ' buffer for version info resource 
Dim pData As Long ' pointer to version info data 
Dim nDataLen As Long ' length of info pointed at by pData 
Dim cpl(0 To 3) As Byte ' buffer for code page & language 
Dim cplstr As String ' 8-digit hex string of cpl 
Dim dispstr As String ' string used to display version information 
Dim retval As Long ' generic return value 
' First, get the size of the version info resource. If this function fails, 
then Textl 
' identifies a file that isn't a 32-bit executable/DLL/etc. 
nDataLen = GetFileVersionInfoSize(Text1.Text, pData) 
If nDataLen = 0 Then 
Debug.Print "Not a 32-bit executable!" 
Exit Sub 
























































End If 

' Make the buffer large enough to hold the version info resource. 
ReDim buffer(0 To nDataLen - 1) As Byte 

' Get the version information resource. 

retval = GetFileVersionInfo (Textl.Text, 0, nDataLen, buffer (0)) 

' Get a pointer to a structure that holds a bunch of data. 

retval = VerQueryValue(buffer(0), "\", pData, nDataLen) 





Copy that structure into the one we can access. 
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CopyMemory vffi, ByVal pData, nDataLen 
' Display the full version number of the file. 
dispstr = Trim(Str(HIWORD(vffi.dwFileVersionMS))) & "." & _ 
Trim(Str (LOWORD (vffi.dwFileVersionMS))) & "." & _ 
Trim(Str (HIWORD (vffi.dwFileVersionLS))) & "." & _ 
Trim (Str (LOWORD (vff£i.dwFileVersionLs) ) ) 
Debug.Print "Version Number: "; dispstr 
' Display the type of file it is (1.e., executable, DLL, etc.). 
Select Case vffi.dwFileType 
Case VEFT_APP 
dispstr "Application" 
Case VFT_DLL 
dispstr "Dynamic Link Library (DLL)" 
Case VFT_DRV 
dispstr "Device Driver" 
Case VFT_VXD 
dispstr "Virtual Device Driver" 
Case Else 
dispstr "Unknown" 
End Select 
Debug.Print "File Type: "; dispstr 
' Before reading any strings out of the resource, we must first determine th 


code page 





B 


"\LegalCopyright", 


"\Filel 





' and languag 
retval 


C 


The code to get this information follows. 


VerQueryValue (buffer (0), 





DataLen) 
' Copy that informtion into 


CopyMemory cpl(0), 
' It is necessary 


SwapBy 
SwapBy 


te cpl ( 
te cpl ( 





0), 
2), 








ByVal pData 








to swap 
cpl (1) 
cpl (3) 


"\VarFileInfo\Translation", 





pData, 





, 4 


the first two bytes, 


the byte array. 


as well as the last two bytes. 


' Convert those four bytes into a 8-digit hexadecimal string. 





cplstr 


FixedHex(cpl (0), 
FixedHex (cpl (3), 


2) 
2) 


& FixedHex(cpl (1), 





2) & FixedHex(cpl(2), 2) & 





' cplstr now represents the code page and language to read strings as. 


' Read the copyright 




































































information from the version 


info resource. 

















& cplstr & 





retval = VerQueryValue (buffer(0), "\StringFileInfo\" 
pData, nDatalLen) 
' Copy that data into a string for display. 
dispstr = Space (nDataLen) 
retval = lstrcpy(dispstr, pData) 
' Display the result. 
Debug.Print "Copyright Info: "; dispstr 
' Similarly, read a description of the file and display it. 
retval = VerQueryValue (buffer(0), "\StringFileInfo\" & cplstr & 
Description", 
pData, nDatalLen) 
dispstr = Space (nDataLen) 
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retval = lstrcpy(dispstr, pData) 








Debug.Print "File Description: "; dispstr 
End Sub 





See Also 


GetFileVersionInfo 





Category 


Files 


Back to the Function list. 





Back to the Reference section. 





Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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GetFocus Function 


Declare Function GetFocus Lib "user32.d1l1" () As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetFocus obtains a handle to the window in the calling thread that has the input focus. If another program has the input 
focus, however, this function will not work and will report an error. 





Return Value 


If successful, the function returns a handle to the window that has the input focus. If an error occured, or if another program 
has the input focus, the function returns zero (use GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


Print the title of the window that currently has the input focus, if our program has it. If not, inform the user that some other 
program has int focus. This is done whenever timer timCheck elapses, so to use this example, you must first place a timer 
named timCheck on a form window. 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetFocus Lib "user32.d11" () As Long 
Public Declare Function GetWindowTextLength Lib "user32.d11" Alias 
"GetWindowTextLengthA" _ 
(ByVal hWnd As Long) As Long 
Public Declare Function GetWindowText Lib "user32.dl11" Alias "GetWindowTextA" 
hWnd As Long, 
ByVal lpString As String, ByVal nMaxCount As Long) As Long 



































' *** Place the following code inside the form window. *** 


Private Sub timCheck_Timer () 


Dim hWnd As Long ' window that has the focus 
Dim wintext As String ' title of the window 
Dim textlen As Long ' length of the title 





' First, see which window in the program, if any, has the input focus. 


hWnd = GetFocus () 
If hWnd = 0 Then 
Debug.Print "This program does not have the input focus." 








Else 

' Get the title of the window that has the focus. 

textlen = GetWindowTextLength (hWnd) + 1 

wintext = Space (textlen) 

textlen = GetWindowText (hWnd, wintext, textlen) 
' Display the title, removing the terminating null. 
Debug.Print "The window titled '" & Left (wintext, textlen) & 























the focus." 
End If 
End Sub 


See Also 


SetFocus 


Category 


Windows 


Back to the Function list. 
Back to the Reference section. 








Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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shop.com | 
GetForegroundWindow Function 
Declare Function GetForegroundWindow Lib "user32.dl1" () As Long 


Platforms: Win 95/98, Win NT 


GetForeground Window finds which window is currently the foreground window. The foreground window is the 
window, usually at the top of the Z-order, with which the user is currently working with -- i.e., the window with the 
focus. The function returns 0 if an error occured, or the handle of the foreground window if successful. 


Example: 


' Display the title bar text of the foreground window. 

















Dim hforewnd As Long ' receives handle of foreground window 

Dim slength As Long ' length of foreground window's title bar text 

Dim wintext As String ' buffer for foreground window's title bar text 

Dim retval As Long ' return value 

hforewnd = GetForegroundWindow () ' determine the foreground window 

slength = GetWindowTextLength(hforewnd) + 1 ' length of its title bar text 
wintext = Space (slength) ' make room in the buffer to receive the text 

retval = GetWindowText (hforewnd, wintext, slength) ' get title bar text 

wintext = Left (wintext, slength - 1) ' remove null character from end of string 
Debug.Print "The window "; wintext; " is the foreground window." 


See Also: SetForegroundWindow 
Category: Windows 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getforegroundwindow.html 
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GetFullPathName Function 








Declare Function GetFullPathName Lib "kernel32.dl1" Alias "GetFullPathNameA" (ByVal 
lpFileName As String, ByVal nBufferLength As Long, ByVal lpBuffer As String, ByVal 
lpFilePart As String) As Long 























Platforms: Win 32s, Win 95/98, Win NT 


GetFullPathName appends a specified filename to the name of the current directory. For example, if you specify the file 
"hello.txt" and the current directory is "C:\My Documents\Junk", the resulting filename would be "C:\My 
Documents\Junk\hello.txt". This string is put into the string passed as lpBuffer. The function returns 0 if an error occured, or 
the length of the final string if successful. 


lpFileName 
The name of the file to append. 
nBufferLength 
The size in characters of [pBuffer. 
lpBuffer 
A string variabled that receives the null-terminated combined path and filename. 
lpFilePart 
??? (appears to have no effect) 


Example: 


' Append the filename datafile.dat to C:\Programs\Test 











Dim buffer As String ' receives path and filename string 

Dim numchar As Long ' receives length of buffer after function call 

ChDir "\Programs\Test" ' change current directory to C:\Programs\Test 

buffer = Space (255) ' make room for buffer to receive the string 

numchar = GetFullPathName ("datafile.dat", 255, buffer, "") ' put the result string 
into buffer 

buffer = Left (buffer, numchar) ' extract data from the returned string 

Debug.Print buffer ' display resulting string 








See Also: GetShortPathName 
Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





http://216.26.168.92/vbapi/ref/g/getfullpathname.html (1 of 2) [9/1/2002 5:23:46 PM] 


Windows API Guide: GetFullPathName Function 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 
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gethostbyaddr Function 


Declare Function gethostbyaddr Lib "wsock32.d11" (addr As Long, ByVal length As Long, 
ByVal protocol As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


gethostbyaddr gets information about a host computer. The computer is identified by its network address (usually but not 
necessary an IP address). The information about the host is placed into a HOSTENT structure, a pointer to which is returned 
by the function. 


Return Value 


If successful, the function returns a pointer to a HOSTENT structure that contains data about the host. This pointer is only 





guaranteed to be valid until the next call to a Winsock function. If an error occured, the function returns zero (use 
WSAGetLastError to get the error code. 





Visual Basic-Specific Issues 


To access the returned data, use CopyMemory to copy the data referenced by the pointer into a HOSTENT structure allocated 
by your program. See the example for a demonstration of this. 


Parameters 


addr 
The address of the host computer to get information about. This address must be in network byte order. 
length 
The length in bytes of the address. For IP addresses, this will be 4. 
protocol 
One of the following flags specifying the type of address specified in addr. The flag identifies the protocol in which the 
address is used. 
AF_12844 
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TEEE 1284.4 WG AF Protocol. 
AF_APPLETALK 

Appletalk protocol. 
AF_ATM 

Native ATM services protocol. 
AF_BAN 

Banyan protocol. 
AF_CCITT 

One of the CCITT protocols (such as X.25). 
AF_CHAOS 

One of the MIT CHAOS protocols. 
AF_CLUSTER 

Microsoft Wolfpack protocol. 
AF_DATAKIT 

One of the Datakit protocols. 
AF_DECnet 

DECnet protocol. 
AF_DLI 

Direct Data Link interface. 
AF_ECMA 

A European Computer Manufacturers protocol. 
AF_FIREFOX 

A FireFox protocol. 
AF_HYLINK 

NSC Hyperchannel protocol. 
AF_IMPLINK 

Arpanet IMP address. 
AF_INET 

Internet or other inter-network address (such as UDP/IP or TCP/IP). 
AF_INET6 

Internet or other inter-network address using IPv6 addresses. 
AF_IPX 

One of the IPX protocols (such as IPX or SPX). 
AF_ISO 

One of the ISO protocols. 
AF_LAT 

LAT protocol. 
AF_NETBIOS 

NetBIOS protocol. 
AF_NS 

One of the Xerox NS protocols, including IPX. 
AF_OSI 

One of the ISO protocols. (Same as AF_ISO.) 
AF_PUP 

A PUP protocol address. 
AF_SNA 

IBM SNA protocol. 
AF_UNIX 

A Unix-type local-to-host pipe or portal. 
AF_UNKNOWNI1 

An unknown protocol. 
AF_VOICEVIEW 
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VoiceView protocol. 


Constant Definitions 



















































































16 


24 
9 
2 


19 
5 
3 





Const AF_12844 = 25 
Const AF_APPLETALK 
Const AF_ATM = 22 
Const AF_BAN = 21 
Const AF_CCITT = 10 
Const AF_CHAOS = 5 
Const AF_CLUSTER = 
Const AF_DATAKIT = 
Const AF_DECnet = 1 
Const AF_DLI = 13 
Const AF_ECMA = 8 
Const AF_FIREFOX = 
Const AF_HYLINK = 1 
Const AF_IMPLINK = 
Const AF_INET = 2 
Const AF_INET6 = 23 
Const AF_IPX = 6 
Const AF_ISO = 7 
Const AF_LAT = 14 
Const AF_NETBIOS = 
Const AF_NS = 6 
Const AF_OSI = 7 
Const AF_PUP = 4 
Const AF_SNA = 11] 
Const AF_UNIX = 
Const AF_UNKNOWN1 = 
Const AF_VOICEVIEW 
Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 


' This code is licensed according to the tern 





' Declarations and such needed 


' (Copy them to 
Public Type WSA 








for the exampl 


£ 





the (declarations) section o 
WSADATA 
wVersion As Integer 
wHighVersion As Integer 











szDescription As String * 257 
szSystemStatus As String * 129 





iMaxSockets As Long 


ns and conditions listed here. 


e: 
a module.) 
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iMaxUdpDg As Long 
lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dl1l" (ByVal wVersionRequested As 























Integer, lpWSAData _ 

As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d1l1" () As Long 
Public Type HOSTENT 

h_name As Long 

h_aliases As Long 

h_addrtype As Integer 

h_length As Integer 

h_addr_list As Long 

















End Type 
Public Const AF_INET = 2 
Public Declare Function htonl Lib "wsock32.d1ll" (ByVal hostlong As Long) As Long 
Public Declare Function gethostbyaddr Lib "wsock32.dll" (addr As Long, ByVal length 
As Long, ByVal _ 

protocol As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 






































As Any, Source _ 
As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString 








As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl] 
As Any, ByVal _ 

lpString2 As Any) As Long 
Public Type INITCOMMONCONTROLSEX TYPE 

dwSize As Long 

dwICC As Long 
























































End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 

INITCOMMONCONTROLSEX TYPE) As Long 
ublic Const ICC_INTERNET_CLASSES = &H800 
ublic Declare Function CreateWindowEx Lib "user32.d1l1" Alias "CreateWindowExA" 
ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 

As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 

hWndParent As Long, 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d1l1" (ByVal hWnd As Long) As Long 



































tg 














AU) 























~ 













































































Public Declare Function SendMessage Lib "user32.dll" Alias "SendMessageA" (ByVal hWnd 








As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 

Public Const IPM ISBLANK = &H469 

Public Const IPM GETADDRESS = &H466 
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xxx Place the following code in a form window. 


When the form is initialized, 
upper-left corner of the 








form. 





Private Sub Form_Initialize() 


register 


0, 

















Dim comctls As INITCOMMONCONTROLSEX TYPE i 














Dim retval As Long 





KK* 


handle to the IP Address control 


create an IP Address control in the 


identifies the control to 


generic return value 


' Register the IP Address control window class. 























With comctls 

.dwSize = Len(comctls) 

-dwICC = ICC_INTERNET_CLASSES 
End With 
retval = InitCommonControlsEx(comctls) 








" Create the IP Address control in the corner of the window. 








hiIPControl 
20y; 


CreateWindowEx (0, 





t25; 


Me.hWnd, 0, 


End Sub 





WC_IPAD 


App.hInstance, 


DRI 











ESS, 





Private Sub Form Unload (Cancel As Integer) 





' 


' 





Dim retval As Long ' 





retval 





End Sub 


Look up the primary domain name of the host computer identified by the 


























return value 


DestroyWindow (hIPControl) 








wee 
r 


ByVal CLng(0)) 


Destroy the IP Address control when the form closes. 
































WS_CHILD Or WS_VISI 














implementation 
the host computer 


the host computer 


address in the IP Address control. 

Private Sub cmdGetDomain_Click () 
Dim ipAddress_h As Long ' the IP address, in host byte order 
Dim ipAddress_n As Long ' the IP address, in network byte order 
Dim sockinfo As WSADATA ' information about the Winsock 
Dim pHostinfo As Long ' pointer to information about 
Dim hostinfo As HOSTENT ' information about the host computer 
Dim domainName As String ' the primary domain name of 
Dim retval As Long ' generic return value 














' Verify that an IP address 
retval = SendMessage(hIPControl, 
If retval <> 0 Then 
Debug.Print 
Exit Sub 











End If 











was entered. 
IPM ISBLANK, 

















ByVal CLng (0), 


"No IP address was entered!" 


' Get the IP address entered by the user and verify that all 





' four fields in the address were entered. 





retval = SendMessage(hIPControl, 

















IPM GETAD 





DR 








ESS, ByVal CLng (0), 
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If retval < 4 Then 
Debug.Print "An incomplete IP address was entered!" 
Exit Sub 











End If 








' Open up a Winsock v2.2 session. 
retval = WSAStartup(&H202, sockinfo) 
If retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 














End If 











" Convert the IP address into network byte order. 

ipAddress_n = htonl(ipAddress_h) 

' Get information about the host computer. 

pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 

If pHostInfo = 0 Then 

Debug.Print "Could not find a host with the specified IP address." 


























Else 








' Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 














' Copy the host domain name into a string. 
domainName = Space(lstrien(hostinfo.h_name) ) 





retval = lstrcpy(domainName, hostinfo.h_name) 








Debug.Print "Domain name is: "; domainName 
End If 














' End the Winsock session. 


retval = WSACleanup () 
End Sub 








See Also 
gethostbyname 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 





Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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gethostbyname Function 


Declare Function gethostbyname Lib "wsock32.dl1" (ByVal name As String) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


gethostbyname gets information about a host computer. The computer is identified by its domain name. The information 
about the host is placed into a HOSTENT structure, a pointer to which is returned by the function. Note that gethostbyname 
cannot identify a host computer by its IP address string. (To get information about a computer with a particular IP address, 
use gethostbyaddr instead.) 


Return Value 


If successful, the function returns a pointer to a HOSTENT structure that contains data about the host. This pointer is only 





guaranteed to be valid until the next call to a Winsock function. If an error occured, the function returns zero (use 
WSAGetLastError to get the error code). 





Visual Basic-Specific Issues 


To access the returned data, use CopyMemory to copy the data referenced by the pointer into a HOSTENT structure allocated 
by your program. See the example for a demonstration of this. 


Parameters 


name 
The domain name of the network host to get information about. This cannot be an IP address string. 


Example 


Print the IP address associated with a domain name specified by the user. Winsock is briefly used to resolve the domain name 
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and format a printable IP address string. The user enters the domain name to resolve in text box txtDomain, and the domain 
name is resolved when the user clicks button cmdGetIP. 


To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window. 


This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 

wVersion As Integer 

wHighVersion As Integer 

szDescription As String * 257 

szSystemStatus As String * 129 

iMaxSockets As Long 

iMaxUdpDg As Long 

lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dl11" (ByVal wVersionRequested As 
Integer, lpWSAData _ 

As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 
Public Type HOSTENT 

h_name As Long 

h_aliases As Long 

h_addrtype As Integer 

h_length As Integer 

h_addr_list As Long 
End Type 
Public Const AF_INET = 2 
Public Declare Function gethostbyname Lib "wsock32.dll1" (ByVal name As String) As 
Long 
Public Declare Function inet ntoa Lib "wsock32.d11" (ByVal inaddr As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 

As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "J 












































strlenA" (ByVal lpString 





As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias 






































lstrcpyA" (ByVal lpStringl 











As Any, ByVal _ 
lpString2 As Any) As Long 


' Define a relevant API macro. 





Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 


MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 


End Function 


xxx Place the following code inside the form window. *** 
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Private Sub cmdGetIP_Click() 
Dim sockinfo As WSADATA ' information about Winsock 
Dim hostinfo As HOSTENT ' information about an Internet host 
Dim pHostinfo As Long ' pointer to a HOSTENT structure 
Dim plPAddress As Long ' pointer to an IP address dword 
Dim ipAddress As Long ' an IP address, packed into a dword 
Dim plIPString As Long ' pointer to an IP address formatted as a string 
Dim ipString As String ' holds a human-readable IP address string 
Dim retval As Long ' generic return value 


' Open up a Winsock session, using version 2.2. 


retval = WSAStartup (MAKEWORD (2, 2), sockinfo) 
If retval <> 0 Then 








Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 
End If 





Get information about the domain specified in txtDomain. 
pHostinfo = gethostbyname (t xtDomain. Text) 

If pHostinfo = 0 Then 

Debug.Print "Unable to resolve domain name." 





Else 

' Copy the data into a HOSTENT structure. 

CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "A non-IP address was returned." 











Else 





' Copy the pointer to the first (and probably only) IP 
address in the structure. 

CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 

' Copy the actual IP address. 

CopyMemory ipAddress, ByVal plIPAddress, 4 





Convert the IP address into a human-readable string. 
piPString = inet ntoa(ipAddress) 
' 


Copy the result into a string variable. 
ipString = Space(lstrien(pIPString) ) 





retval = lstrcpy(ipString, pIPString) 





' Print the result: a human-readable IP address. 
Debug.Print ipString 





End If 
End If 


Close the Winsock session. 
retval = WSACleanup () 
End Sub 


See Also 


gethostbyaddr 
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GetKeyboardState Function 


Declare Function GetKeyboardState Lib "user32.dl1" (lpKeyState As Byte) As 
Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetKeyboardState retrieves the state of every key on the keyboard and places the information into an array. 
Each element of the 256-element array identifies information about the virtual-key whose virtual-key code 
matches the index of the element. If the &H1 bit is set, that key is toggled. If the &H80 bit is set, the key is 
currently pressed down. The keyboard information retrieved by this function is thread-specific; its information 
does not necessarily reflect key states pertaining to the system as a whole. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpKeyState 
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A 256-element byte array which receives the key status information for all virtual-keys. Each key is 
identified by the element corresponding with the key's virtual key code. Windows NT, 2000: In 
addition to the virtual keys, the array also receives information which distinguish between the left and 
right Ctrl, Alt, and Shift keys, which are placed in the array at the following indices: 
VK_LSHIFT 
The left Shift key. 
VK_RSHIFT 
The right Shift key. 
VK_LCONTROL 
The left Ctrl key. 
VK_RCONTROL 
The right Ctrl key. 
VK_LMENU 
The left Alt key. 
VK_RMENU 
The right Alt key. 





Constant Definitions 


Const VK_LSHIFT = &HAO 
Const VK_RSHIFT = &HA1 
Const VK_LCONTROL = &HA2 
Const VK_RCONTROL & HA3 
Const VK_LMENU = &HA4 
Const VK_RMENU = &HA5 














Example 


' This code is licensed according to the terms and conditions listed here. 





' Set the toggle status for every key on the keyboard to "not 

" toggled." This change only applies to the current thread. 

Dim keystates(0 To 255) As Byte ' holds states of entire keyboard 
Dim c As Integer ' counter variable 

Dim retval As Long ' return value 








' First, get the current state of the keyboard. 
retval = GetKeyboardState (keystates (0) ) 


' Now, loop through each element and explicitly set the toggle bit to 0. 
For c = 0 To 255 

' Make sure the &H1 bit is not set. 

keystates(c) = keystates(c) And (Not &H1) 
Next c 
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' Finally, set this to the current keyboard state. 
retval = SetKeyboardState (keystates (0) ) 





See Also 


GetKeyState, SetKeyboardState 


Category 


Keyboard 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: September 5, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 Go back 
to the Windows API Guide home page. 
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gethostname Function 








Declare Function gethostname Lib "wsock32.d1ll1" (ByVal name As String, ByVal namelen 
As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


gethostname retrieves the network host name for the computer. This could be a simple host name or a fully-qualified domain 
name. No matter what it is, though, it can be successfully given to gethostbyname to get information about the computer as a 


network host (for example, to get its IP address). 


Return Value 


If successful, the function returns zero. If an error occured, the function returns a non-zero value (use WSAGetLastError to get 





the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


name 
String that receives the host name of the computer, terminated by a null character. This string must have sufficient room 
to receive the string copied into it. 

namelen 
The length of the string passed as name. 


Example 


When the form window opens, create an IP address control in the upper-left corner and initialize it to the IP address of the 
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computer. No special effort is needed to run this example, since the IP Address control is created programmatically when the 


form loads. 





Public T 





End Type 
Public D 
Integer, 





Public D 
Public T 








End Type 
wb dae € 
ublic D 
amelen 
ubl 
ong 
ublic 


E-D 
D 


P 
PÈ 
n 
P 
L 
P 
P. D 











ublic 
As Any, 


Public 
As Any) 
Public 
As Any, 


D 





D 


Public Type INITCOMMONCONTROLS] 





End Type 
Public 





tO 'U 


ublic 
ByVal 








~ 


This code is licensed according to the tern 


DAT 





ype WSA 


wVersion A 
wHighVersi 
szDescript 
szSystemSt 
iMaxSocket 
iMaxUdpDg 

lpVendorI 











n 


ns and conditions listed here. 


Declarations and such needed for the example: 
(Copy them to the 


section of 





(declarations) a module.) 


A 

s Integer 

on As Integer 

ion As String * 257 
atus As String * 129 
s As Long 

As Long 

fo As Long 











eclare F 
lpWSADa 
As WSA 


un 
ta 





DATA 


eclare Fun 


EN 
E 





ype HOSTI 


h_name As 
h_aliases 
h_addrtype 
h_length A 
h_addr_lis 





onst AF_IN 
eclare F 
As Long) 
eclare F 


un 
A 
un 





eclare Fun 


ub 





eclare S 
Source _ 
As Any, 

eclare Fun 
As Long 
eclare F 


ByVal 





un 





lpString2 As Any) 


ByVal lengi 





ction WSAStartup Lib "wsock32.dll" (ByVal wVersionRequested As 





) As Long 
ction WSACleanup Lib "wsock32.d11" 
T 


() As Long 


Long 

As Long 

As Integer 
s Integer 

t As Long 











tion gethostname Lib "wsock32.dl1l1" (ByVal name As String, 
Long 


tion gethostbyname Lib "wsock32.d1] 


ByVal 


ct 
S 
Cl ' 





As 


(ByVal name As String) 

















ction ntohl Lib "wsock32.dl] (ByVal 


CopyMemory Lib "kernel32.d11" Alias 


hostlong As Long) 
( 


As Long 











"RtlMoveMemory" (Destination 





th As Long) 
"kernel32.dl11" 


ction lstrlen Lib Alias "lstrlenA" (ByVal lpString 





























Cc "kernel32.dl1l1" Alias "ls 


( 








tion lstrcpy Lib trcepyA" (ByVal lpStringl 


As Long 
EX TYPE 














dwSize As 
dwICC As L 


Declare Function InitCommonCon 


INI TCOMMON 


Long 
ong 


Ex Lib 





pe a "comct132.d11" (lpInitCtrlis As _ 











m 
D 


CONTROLSEX TYP! 








) As Long 








ublic Const ICC_INT 
Declare Function CreateWindow 


dw] 








ExStyle A 











&H800 
Ex Lib 


ERNET CLASSES 














"user32.d11" EXA" 





Alias "CreateWindow 








s Long, 
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ByVal lpClassName As String, 





























ByVal 


























lpWindowName As String, 






























































ByVal dwStyle As 








Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, _ 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.dll1" (ByVal hWnd As Long) As Long 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM SETADDRESS = &H465 
' Define a relevant API macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val ("&H" & Right ("00" & Hex(bHigh), 2) & Right ("00" & Hex(bLow), 
2)) 
End Function 
' KK* 


xxx Place the following code inside the 


Private hIPControl As Long 


When the form 


is 





initialized, 








' upper-left corner of the form. 
Private Sub Form_Initialize() 
Dim comctls As INITCOMMONCONTROLSEX TYPE i 
register 
Dim sockinfo As WSADATA ' information about 
Dim hostinfo As HOSTENT ' information about 
Dim pHostinfo As Long ' pointer to a HOST! 
Dim localhostName As String ' the 
Dim plIPAddress As Long ' pointer 
Dim ipAddress_n As Long " the 
Dim ipAddress_h As Long '! 
Dim retval As Long ' 











En 
re 





TIPControl 

















Register t 


























he 























form window. 
































ith comctls 

.dwSize = Len(comctls) 

-dwICC = ICC_INTERNET_CLASSES 
d With 
tval = InitCommonControlsEx(comctls) 





handle to the IP Address control 


create an IP Address control in the 


identifies the control to 


Winsock 





an Internet host 





ENT structure 
computer's domain name 

to an IP address dword 

IP address in network byte order 
the IP address in host byte order 


generic return value 





IP Address control window class. 


Create the IP Address control in the corner of the window. 
WS_CHILD Or WS_VIS 





Me . hWnd, 


Open a new Winsock session 


CreateWindowEx (0, 








DRI 








WC_IPAD 





0, 








App.hInstance, 


(version 2.2). 
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r 


ByVal CLng(0) ) 








BL 














retval = WSAS 
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tartup (MAKEWORD (2, 








If retval <> 





Exit 
End If 











' Get the domain name of the computer, 
' that gethostbyname can handle to give an 


localhostName 


retval = gethostname(localhos 
ocalhos 


localhostName 


O Then 











Debug.Print "ERROR: Attempt to open Winsock failed: 


Sub 


= Space (256) 











= Left (] 








' Get informa 








' Get informa 
pHostinfo =g 





tion about this computer on the network. 
tion about the domain specified in txtDomain. 


2), 





sockinfo) 


error"; retval 





£ 





or, failing that, 


IP address. 


a string 





tName, 
tName, 


256) 
InStr(localhostName, 





vbNullChar) - 1) 








ethostbyname (localhostName) 





If pHostinfo 
Debug 








Else 


= 0 Then 
.Print 





"Unable to resolve domain name." 





' Copy the data into a HOSTENT structure. 


CopyMemory hostinfo, 


ByVal 








pHostinfo, Len(hostinfo) 








If hostinfo.h_addrtype <> AF_INET Then 


Else 





in the struct 


End I 





End If 











End Sub 








' Destroy the 











Debug.Print 


' Copy the pointer to the first 


ure. 


CopyMemory pIPAddress, 





"A non-IP address was returned." 


(and probably only) IP 





ByVal hostinfo.h_addr_list, 4 





' Copy the actual IP address. 


CopyMemory ipAddress_n, 
" Convert it 


ipAddress_h 








ByVal plIPAddress, 4 
to host byte order. 
ntohl (ipAddress_n) 





' Set the IP Address control to hold this address. 


retval = SendMessage(hIPControl, 




















IPM SETADDRESS, 











f 


IP Address control when the 


ByVal CLng(0), 





ByVal 





ipAddress_h) 








form closes. 


Private Sub Form_Unload(Cancel As Integer) 





retval 


End Sub 





Category 


Winsock 


Back to the Function list. 


Dim retval As Long ' 











Back to the Reference section. 


return value 


DestroyWindow (hIPControl1) 
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GetKeyState Function 


Declare Function GetKeyState Lib "user32.d1ll1" (ByVal nVirtKey As Long) As 
Integer 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetKeyState determines the current status of a key. The function both finds whether the key is currently pressed down 
or not, and determines if the key is currently toggled. The keyboard information retrieved by this function is thread- 
specific; its information does not necessarily reflect key states pertaining to the system as a whole. 


Return Value 


If the &H1 bit of the return value is set, the key is toggled. If the &H8000 bit of the return value is set, the key is 
currently pressed down. 


Visual Basic-Specific Issues 


None. 


Parameters 


nVirtKey 
The virtual-key code of the key to read the status of. Windows NT, 2000: This could also be one of the 
following flags which distinguish between the left and right Ctrl, Alt, and Shift keys: 
VK_LSHIFT 
The left Shift key. 
VK_RSHIFT 
The right Shift key. 
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VK_LCONTROL 

The left Ctrl key. 
VK_RCONTROL 

The right Ctrl key. 
VK_LMENU 

The left Alt key. 
VK_RMENU 

The right Alt key. 





Constant Definitions 


Const VK_LSHIFT & HAO 
Const VK_RSHIFT = &HA1 
Const VK_LCONTROL = &HA2 
Const VK_RCONTROL = &HA3 
Const VK_LMENU = &HA4 
Const VK_RMENU = &HA5 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function GetKeyState Lib "user32.d1ll1" (ByVal nVirtKey As Long) As 
Integer 


" Determine whether the Q key is currently being pressed. 
' The code runs when button Commandl is pressed. 








Private Sub Command1l_Click () 
Dim keystate As Integer ' state of the Q key 


' Get the state of the Q key as returned by the function. 
' (vbKeyQ is a VB-defined constant for Q's virtual-key code) 
keystate = GetKeyState (vbKey0Q) 
" Check the &H8000 bit of the return value. 
If keystate And &H8000 Then 
Debug.Print "The Q key is currently down." 
Else 
Debug.Print "The Q key is currently up." 
End If 
End Sub 


See Also 


GetAsyncKeyState, GetKeyboardState 


http://216.26.168.92/vbapi/ref/g/getkeystate.html (2 of 3) [9/1/2002 5:24:44 PM] 


Windows API Guide: GetKeyState Function 


Category 


Keyboard 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetLastError Function 
Declare Function GetLastError Lib "kernel32.d1l1" () As Long 
Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetLastError obtains the error code returned by the last API function called. Most API functions merely return a number 
saying if an error occured, but not specifying exactly which error occured. This function gets a universal error code 
identifying the type of error that last occured. Note that most functions set the code to 0 (success) if the function completes 
successfully, erasing the previous error code. Therefore, be sure to check this error code immediately after an error is found. 


Return Value 


The function returns the error code of the last API function called by the program. 


Visual Basic-Specific Issues 


Although GetLastError works perfectly in Visual Basic, it will sometimes not appear to work. This is because Visual 
Basic implicitly uses the API frequently to perform tasks which are seemingly intrinsic to the language. These hidden API 
function calls will usually overwrite the error code which your code may be trying to read. To compensate for this, the 
LastDllError property of the Err object, predefined in Visual Basic, caches the error code from the last API function 
explicitly called by your program. You should use the expression Err.LastDIError instead of the GetLastError function to 
debug failed API function calls. 


Parameters 


None. 


Example 
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' This code is licensed according to the terms and conditions listed here. 





' Demonstrate catching an invalid handle error. 
' If this code does not work, 
Dim retval As Long ' return value of function 
Dim errorcode As Long 














" error code 


to the following function by 
CloseHandle(-1) ' there is no handle -1! 

0 Then ' the return value will be 0 if 
GetLastError () ' find the error code 
6 Then Debug.Print "ERROR: Invalid 


' Make an invalid call 


retval = 

















If retval = 

errorcode = 
If errorcode = 
invalid handle 
End If 














See Also 


CommDIgExtendedError, SetLastError, SetLastErrorEx 





Category 


Errors 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


Last Modified: January 5, 2000 








try replacing "GetLastError()" with Err.LastDllError. 





giving it an invalid handle 
an error occured 


Handle Specified" ' error 6 = 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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GetLocalTime Function 


Declare Sub GetLocalTime Lib "kernel32.d11" (lpSystemTime As 
SYSTEMTIME) 





Platforms: Win 95/98, Win NT 


GetLocalTime returns the system's time and date. The various features of the time and date (month, day, 
hour, minute, second, etc.), down to the millisecond, are sorted in the variable passed as /pSystemTime! 
Windows considers "local time" to be the system's current time. 


lpSystemTime 
Variable that receives the computer's date and time. 


Example: 


' Print the current date in mm-dd-yyyy format 





Dim localtime As SYSTEMTIME ' receives the computer's time and date 
GetLocalTime localtime ' read the computer's time and date 

' Display the date 

Debug.Print localtime.wMonth; "-"; localtime.wDay; "-"; localtime.wYear 


See Also: GetSystemTime 
Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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GetLogicalDrives Function 











Declare Function GetLogicalDrives Lib "kernel32.dll" () As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GetLogicalDrives determines all the valid logical drives on the computer. Logical drives are any drives assigned a one- 
letter name (such as A: or C:). The return value is a collection of single-bit flags identifying the drives found. Perform a 
binary And between the return value and increasing powers of 2 to determine all of the drives. For example, And it with 1 to 
see if drive A: exists, with 2 for B:, 4 for C:, 8 for D:, etc. (See the example for a demonstration.) 


Example: 


' Tell the user which drives exist on the computer. Note how this example 

" only checks up to drive D:, but it does establish the necessary pattern to use in 
general. 

Dim driveflags As Long ' receives the flags identifying valid drives 




















' Get the valid logical drives on the computer. 

driveflags = GetLogicalDrives () 

' Test the returned value to see if drives A: through D: exist. 
I (driveflags And 1) = 1 Then Debug.Print "Drive A: exists." 
(driveflags And 2) = 2 Then Debug.Print "Drive B: exists." 
(driveflags And 4) = 4 Then Debug.Print "Drive C: exists." 
(driveflags And 8) = 8 Then Debug.Print "Drive D: exists." 

" And so on.... 























f 
I£ 
If 

f 




















See Also: GetLogicalDriveStrings 
Category: Files 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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GetLogicalDriveStrings Function 








Declare Function GetLogicalDriveStrings Lib "kernel32.d11" Alias 
"GetLogicalDriveStringsA" (ByVal nBufferLength As Long, ByVal lpBuffer As String) As 
Long 




















Platforms: Win 95/98, Win NT 


GetLogicalDriveStrings determines the valid logical drives on the computer and places the names of their root directories 
into the string passed as /pBuffer. Each root directory name in the buffer is separated by a null character, and the entire string 
ends in two null characters. For example, if only drives A: and C: exist, the string will be "a:\(null)c:\(null)(null)", where 
(null) represents the null character. The function returns 0 if an error occured, or the length of the string placed in /pBuffer if 
successful. 


nBufferLength 
The size of the buffer string passed as lpBuffer. 
[pBufferA string which receives the names of all the logical drives. This must have enough room to receive the string. 








Example: 

' List the names of all the root directories. Since each entry in the string takes 
' four characters (three for the name and one for the null), we can "count by fours" 
going 

' through the string until we reach the end. This frees us from worrying about 





nulls. 

Dim drivenames As String ' receives list of root names 

Dim thisdrive As String ' buffer for one extracted root directory name 
Dim c As Long ' counter variable 

Dim slength As Long ' receives length of returned string 











' Make enough room in the buffer to receive the drive names. 

















drivenames = Space (255) ' more than enough room 
' Get the root directory names of all logical drives. 
slength = GetLogicalDriveStrings (255, drivenames) ' drivenames now holds the list 
" Count by fours to extract the names of each drive. 
For c = 1 To slength Step 4 ' loop with an increment of 4 
thisdrive = Mid(drivenames, c, 3) ' extract a 3-character string X:\ (X is the 
drive letter) 
Debug.Print thisdrive ' display the drive name 
Next c 


See Also: GetLogicalDrives 
Category: Files 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/¢g/getlogicaldrivestrings.html 
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GetMenu Function 


Declare Function GetMenu Lib "user32.d11" (ByVal hWnd As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetMenu identifies what menu is assigned to a given window. This menu appears as the window's menu bar, although 
programatically the menu bar is just the top menu in the menu heirarchy. 


Return Value 


The function returns a handle to the menu assigned to the specified window. If the window has no menu, the function returns 





0. If the window specified in the parameter list is a child window, the function's return value is meaningless. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to get the menu of. 


Example 


Before running this example, use the Menu Editor utility to create a small menu system on Form1. It doesn't matter what the 
menus look like, but some sort of menus are necessary. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
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' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetMenu Lib "user32.dl1l1" (ByVal hWnd As Long) As Long 
Public Declare Function GetMenulItemCount Lib "user32.dll" (ByVal hMenu As Long) As 
Long 
Public Type MENUITEMINFO 

cbSize As Long 
fMask As Long 
fType As Long 
fState As Long 

wID As Long 

hSubMenu As Long 

hbmpChecked As Long 

hbmpUnchecked As Long 

dwItemData As Long 

dwTypeData As String 

cch As Long 
End Type 
Public Const MIIM_STATE = &H1 
Public Const MIIM_ SUBMENU = &H4 
Public Const MIIM_TYPE = &H10 
P 
P 
P 

( 













































































ublic Const MFT SEPARATOR = &H800 

ublic Const MFS_ CHECKED = &H8 

ublic Declare Function GetMenultemInfo Lib "user32.dll" Alias "GetMenuItemInfoA" 
ByVal 















































hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As _ 
MENUITEMINFO) As Long 





























' When button Commandl is pressed, output the structure of th ntire menu system 
' of Forml to the Debug window. Th ntire menu heirarchy is displayed, and any 
items 








' that are checked are identified. A recursive subroutine is used to output the 
contents 
' of each individual menu, calling itself whenever a submenu is found. 





' *** Place the following code inside a module. *** 
' This function performs the recursive output of the menu structure. 
Public Sub IterateThroughIitems (ByVal hMenu As Long, ByVal level As Long) 



























































' hMenu is a handle to the menu to output 

' level is the level of recursion, used to indent submenu items 

Dim itemcount As Long ' the number of items in the specified menu 
Dim c As Long ' loop counter variable 

Dim mii As MENUITEMINFO ' receives information about each item 

Dim retval As Long ' return value 

' Count the number of items in the menu passed to this subroutine. 
itemcount = GetMenultemCount (hMenu) 








' Loop through the items, getting information about each one. 


























With mii 
.CbSize = Len (mii) 
.fMask = MIIM_STATE Or MIIM TYPE Or MIIM_SUBMENU 
For c = 0 To itemcount = 1 
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' Make room in the string buffer. 
-dwTypeData = Space (256) 

















-cch = 256 

' Get information about the item. 

retval = GetMenulItemInfo(hMenu, c, 1, mii) 

' Output a line of information about this item. 

















If mii.fType = MFT_SEPARATOR Then 
' This is a separator bar. 



























































Debug.Print " T & String(3 * level, ".") & "“----- i 
Else 
' This is a text item. 
' If this is checked, display (X) in the margin. 
Debug.Print IIf(.fState And MFS_CHECKED, "(X)", " 
"); 
' Display the text of the item. 
Debug.Print String(3 * level, ".") & 
Left (.dwTypeData, .cch) 
' If this item opens a submenu, display its contents. 
If .hSubMenu <> 0 Then 
IterateThroughItems .hSubMenu, level + 1 
End If 
End If 
Next c 
End With 





End Sub 





' *** Place the following code inside Forml. *** 

' When Commandl is clicked, output the entire contents of Forml's menu system. 
Private Sub Commandl_Click () 

Dim hMenu As Long ' handle to the menu bar of Forml 








' Get a handle to Forml's menu bar. 
hMenu = GetMenu (Forml .hWnd) 
' Use the above function to output its contents. 
IterateThroughItems hMenu, 0 
End Sub 








See Also 


GetS ystemMenu 


Category 


Menus 


Back to the Function list. 
Back to the Reference section. 
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Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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GetMenultemCount Function 
Declare Function GetMenulItemCount Lib "user32.d11" (ByVal hMenu As Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetMenultemCount counts the number of items in a menu. Keep in mind that the position indexes of menu items are zero 
based. This means that if there are n items in the menu, their position indexes go from 0 ton - 1. 


Return Value 


If successful, the function returns the number of items in the menu. If an error occured, the function returns -1 (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the menu to count the items of. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

' There's quite a few declarations for this example, but it's worth it! 

Public Declare Function GetSystemMenu Lib "user32.d1l1" (ByVal hWnd As Long, ByVal 
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bRevert _ 
As Long) As Long 


Public Declare Function GetMenuItemCount Lib "user32.dl1" (ByVal hMenu As Long) As 





Long 
Public Type MENUITEMINFO 
cbhSize As Long 
fMask As Long 
fType As Long 
fState As Long 
wID As Long 
hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 
cch As Long 
End Type 
ublic Con 
ublic Con 
ublic Con 






































[IM STATE = &H1 
IIM_ID = &H2 
IIM_TYPE = &H10 

FT SEPARATOR = &H800 
ublic Con FT_STRING = &HO 
ublic Con FS ENABLED = &HO 
ublic Const MFS_ CHECKED = &H8 


























is = SS Ss is 


S 
S 
S 
st 
S 
S 




































































P 
P 
P 
Public Con 
P 
P 
P 
P 
( 


ByVal _ 








hMenu As Long, ByVal ulItem As Long, ByVal 








ByPosition As Long, 











As MENUITEMINFO) As Long 














tg 











~ 


ByVal _ 
hMenu As Long, ByVal uItem As Long, ByVal 








F 





ByPosition As Long, 











As MENUITEMINFO) As Long 











ublic Declare Function InsertMenuItem Lib "user32.dqdll" Alias "InsertMenulItemA" 


lpmii _ 








ublic Declare Function SetMenuItemInfo Lib "user32.d1l1" Alias "SetMenulItemInfoA" 





lpmii _ 


Public Declare Function SetWindowPos Lib "user32.dll1" (ByVal hWnd As Long, ByVal _ 



































hWndiInsertAfter As Long, ByVal x As Long, 
ByVal _ 

cy As Long, ByVal wFlags As Long) As Long 
Public Const HWND_TOPMOST = -1 
Public Const HWND_NOTOPMOST = -2 














Public Const SWP_NOMOVE = &H2 
Public Const SWP_NOSIZE = &H1 


























Public Declare Function SetWindowLong Lib "user32.d1l1" Alias 














ByVal y As Long, 








ByVal cx As Long, 





"SetWindowLongA" (ByVal 


As Long 


hWnd _ 
As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) 
Public Const GWL_WNDPROC = -4 
Public Declare Function CallWindowProc Lib "user32.d1ll" Alias "CallWindowProcA" 

















~ 


ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, 
As Long, ByVal lParam As Long) As Long 
Public Const WM SYSCOMMAND = &H112 
Public Const WM INITMENU = &H116 
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ByVal wParam _ 
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' Add an option to make window Forml "Always On Top" to the bottom of its system 

' menu. A check mark appears next to this option when active. The menu item acts as 
a toggle. 

' Note how subclassing the window is necessary to process the two messages needed 

' to give the added system menu item its full functionality. 














' *** Place the following code in a module. *** 





Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public ontop As Boolean ' identifies if Forml is always on top or not 














' The following function acts as Forml's window procedure to process messages. 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 
































As Long, ByVal lParam As Long) As Long 
Dim hSysMenu As Long ' handle to Forml's system menu 
Dim mii As MENUITEMINFO ' menu item information for Always On Top 
Dim retval As Long ' return value 


Select Case uMsg 

Case WM INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 













































































With mii 
' Size of the structure. 
.cbSize = Len(mii) 
' Only use what needs to be changed. 
.£fMask = MIIM_ STATE 
' If Forml is now always on top, check the item. 
.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenultemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 





Case WM SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 








top 





' setting of Forml to match. 

If wParam = 1 Then 
" Reverse the setting and make it the current one. 
ontop = Not ontop 
retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 




















HWND_NOTOPMOST), 





O, O, 0; 0; SWP_NOMOVE Or SWP_NOSTIZI 








Cd 
—_ 














WindowProc = 0 
Else 
' Some other item was selected. Let the previous window 
procedure 
' process it. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, 
lParam) 
End If 
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Case Else 
T 





If this is some other message, let the previous procedure handle 
it. 

WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 
End Select 
End Function 











' 


xxx Place the following code inside Forml. *** 


' When Forml loads, add Always On Top to the system menu and set up the 























new window procedure. 
Private Sub Form_Load() 
Dim hSysMenu As Long ' handle to the system menu 
Dim count As Long ' the number of items initially on the menu 
Dim mii As MENUITEMINFO ' describes a menu item to add 
Dim retval As Long ' return value 





Get a handle to the system menu. 
hSysMenu = GetSystemMenu(Forml.hWnd, 0) 








See how many items are currently in it. 
count = GetMenuItemCount (hSysMenu) 

' Add a separator bar and then Always On Top to the system menu. 
With mii 

' The size of the structure. 

.cbSize = Len (mii) 

' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 

.fType = MFT_SEPARATOR 


It has an ID of 0. 






































-wID = 0 
End With 
' Add the separator to the end of the system menu. 
retval = InsertMenulItem(hSysMenu, count, 1, mii) 











Likewise, add the Always On Top command. 
With mii 





.fMask = MIIM_STATE Or MIIM_ID Or MIIM_ TYP] 
This is a regular text item. 

.fType = MFT_STRING 

The option is enabled. 

-fState = MFS_ ENABLED 
It has an ID of 1 (this identifies it in the window procedure). 











Cl 




































































.wID = 1 
' The text to place in the menu item. 
-dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenulItem(hSysMenu, count + 1, 1, mii) 
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' Set the custom window procedure to process Forml's messages. 


ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf 


End Sub 




















' Before unloading, restore the default system menu and remove the 
' custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














' Replace the previous window procedure to prevent crashing. 





retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
' Remove the modifications made to the system menu. 
retval = GetSystemMenu(Forml.hWnd, 1) 

End Sub 


























Category 


Menus 


Back to the Function list. 
Back to the Reference section. 





Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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GetMenultemIinfo Function 


























Declare Function GetMenulItemInfo Lib "user32.d1l1" Alias "GetMenulItemInfoA" (ByVal 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As MENUITEMINFO) 
As Long 









































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetMenultemInfo retrieves information about an item on a menu. The type of information retrieved is determined by the 
flags specified by the fMask data member of the structure passed as the /pmii parameter. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the menu that contains the item to get information about. 

ultem 
Identifies the menu item to get information about. This could be either a position or a menu item identifier, depending 
on fByPosition. 

JByPosition 
If this is a non-zero value, ultem indicates the item by using its zero-based position. (For example, the first item in the 
menu has a position of 0.) If this is zero, then ultem is the unique menu item identifier of the item. 

Ipmii 
Receives information about the menu item. Before calling GetMenultemInfo, the cbSize and fMask data members of 
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this structure must be initialized to specify what information about the item to retrieve. If getting the text of the menu 
item, the dwTypeData and cch data members must also be initialized to receive the string. (See the example below for a 
demonstration of this.) 


Example 


Before running this example, use the Menu Editor utility to create a small menu system on Form1. It doesn't matter what the 
menus look like, but some sort of menus are necessary. 


i 


This code is licensed according to the terms and conditions listed here. 





(Copy them to the 


Public 
Public 
Long 


Public Type M 





P 
P 
P 
P 
P 
P 

( 


' 


ublic 


ublic 


ublic 


ublic 


ublic 





ublic 





ByVal 





Declare Function GetMenu 








Declarations and such needed for the example: 
(declarations) section of a module.) 








Lib "user32.dl1" (ByVal hWnd As Long) As Long 








Declare Function GetMenulItemCount Lib "user32.d1l1" (ByVal hMenu As Long) As 











ENUIT 





EMINFO 








cbhSize As Long 








fMask As Long 
fType As Long 
fState As Long 


wID As Long 

hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwItemData 
dwTypeData 
cch As Long 





End Type 


Const 
Const 
Const 
Const 
Const 








hMenu As Long, 








As Long 
As String 





MIIM_STATE = &H1 








MIIM_SUBMENU = &H4 














MIIM_ 


TYPE = &H10 





MFT_SI] 








MFS_C 





HECKED = &H8 




















MENUIT 








EMINFO) As Long 








EPARATOR = &H800 








Declare Function GetMenulItemInfo Lib "user32.dl11" Alias "GetMenuItemInfoA" 

















ByVal ulItem As Long, ByVal fByPosition As Long, lpmii As _ 








When button Commandl is pressed, output the structure of th ntire menu system 


of 





items 


' 


that ar 


Forml to the 





Debug window. 





contents 


i 


' 


of each individual menu, call 


KK* P 


This 
Public Sub IterateThroughItems ( 
' hMenu is a handle to 


£ 





' level is the level of 


function peri 











Th ntire menu heirarchy is displayed, and any 





checked are identified. A recursive subroutine is used to output the 


ing itself whenever a submenu is found. 














lace the following code inside a module. *** 
forms the recursive output of the menu structure. 





ByVal hMenu As Long, ByVal level As Long) 





the menu to output 





recursion, used to indent submenu items 
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Dim itemcount As Long ' the number of items in the specified menu 
Dim c As Long ' loop counter variable 

Dim mii As MENUITEMINFO ' receives information about each item 

Dim retval As Long ' return value 





" Count the number of items in the menu passed to this subroutine. 
itemcount = GetMenultemCount (hMenu) 

















' Loop through the items, getting information about each one. 



































With mii 
.cbSize = Len (mii) 
.fMask = MIIM_STATE Or MIIM TYPE Or MIIM_ SUBMENU 
For c = 0 To itemcount = 











' Make room in the string buffer. 
-dwTypeData = Space (256) 
-cch = 256 
' Get information about the item. 
retval = GetMenuItemInfo(hMenu, c, 1, mii) 
' Output a line of information about this item. 
If mii.fType = MFT_SEPARATOR Then 
' This is a separator bar. 






















































































Debug.Print " " & String(3 * level, ".") g "----- " 
Else 
' This is a text item. 
' If this is checked, display (X) in the margin. 
Debug.Print IIf(.fState And MFS_CHECKED, "(X)", " 
"); 
' Display the text of the item. 
Debug.Print String(3 * level, ".") & 
Left (.dwTypeData, .cch) 
' If this item opens a submenu, display its contents. 
If .hSubMenu <> 0 Then 
IterateThroughItems .hSubMenu, level + 1 
End If 
End If 
Next c 
End With 





End Sub 





' ***x Place the following code inside Forml. *** 

' When Commandl is clicked, output the entire contents of Forml's menu system. 
Private Sub Command1_Click () 

Dim hMenu As Long ' handle to the menu bar of Forml 











' Get a handle to Forml's menu bar. 

hMenu = GetMenu (Forml.hWnd) 

' Use the above function to output its contents. 
IterateThroughItems hMenu, 0 

End Sub 

















See Also 
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SetMenultemInfo 





Category 


Menus 


Back to the Function list. 
Back to the Reference section. 
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GetNumberFormat Function 


Declare Function GetNumberFormat Lib "kernel32.d1l1" Alias "GetNumberFormatA" (ByVal 
Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat As Any, 
ByVal lpNumberStr As String, ByVal cchNumber As Long) As Long 



































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetNumberFormat formats a number for display. By default, the function formats the number according to the specified 
locale's settings. However, custom formatting preferences can instead be used. The end result of GetNumberFormat is a 
number displayed according to the user's preferences. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
number of characters copied into the string passed as JpNumberStr, not including the terminating null character. 


Visual Basic-Specific Issues 


When passing 0 for the /pFormat parameter, the expression ByVal CLng(0) must be used. See the example code for a 
demonstration of this. 


Parameters 


Locale 
The locale identifier of the locale to format the number according to. This identifier could be generated by the 
MAKELCID macro. Alternatively, this could be one of the following flags specifying a locale: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
The user's default locale. 
dwFlags 
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If no structure is passed as /pFormat, this parameter determines the settings used to format the number. If this is 0, the 
current locale settings are used. Or, this could be the following flag: 
LOCALE_NOUSEROVERRIDE 
Use the system's default settings for the locale, regardless of any modifications the user may have made to it. 
lpValue 
A string containing the number to format. The only allowable characters in this string are the digits 0-9 and at most a 
single decimal point character (.). If the number is negative, the first character in the string must be a minus sign 
character (-). Any other characters are invalid. 
lpFormat 
To override the locale's formatting settings, pass a NUMBERFMT structure that contains the appropriate formatting 
information. To use the locale's settings instead, pass 0 for this parameter. 
lpNumberStr 
String that receives the null-terminated formatted number string. This string must have enough room to receive the 
string. 
cchNumber 
The number of characters in the string passed as [pNumberStr. 





Constant Definitions 





Const LOCALE SYSTEM DEFAULT = &H400 
Const LOCALE _USER_DEFAULT = &H800 
Const LOCALE NOUSEROVERRIDE = &H80000000 



























































Example 


F 


This code is licensed according to the terms and conditions listed here. 


' 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type NUMBERFMT 

NumDigits As Long 

LeadingZero As Long 

Grouping As Long 

lpDecimalSep As String 

lpThousandSep As String 

NegativeOrder As Long 
End Type 
Public Declare Function GetNumberFormat Lib "kernel32.d11" Alias "GetNumberFormatA" _ 
(ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, 















































lpFormat 


As Any, ByVal lpNumberStr As String, ByVal cchNumber As Long) As Long 
Const LOCALE_USER_DEFAULT = &H800 












































' Display the number -1,234,567.89 according to two formatting rules. 
' 1. Use the format specified by the current user locale. 
' 2. Use a custom format specified by a structure passed to the function. 



































Dim nft As NUMBERFMT ' custom formatting settings 
Dim formatted As String ' receives the formatted number strings 
Dim strlen As Long ' the length of the formatted string 
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' Display the number formatted according to the current locale. 

formatted = Space (256) 

strlen = GetNumberFormat (LOCALE_USER_DEFAULT, 0, "-1234567.89", ByVal CLng(0), _ 
formatted, Len(formatted) ) 

formatted = Left (formatted, strlen) 

Debug.Print "User locale format: "; formatted 















































' Now display according the format we specify below. 
With nft 





' Display three digits after the decimal point. 
-NumDigits = 3 
' Display zeros after the decimal point. 
.LeadingZero = 1 
' Group every three digits to the left of the decimal. 
.Grouping = 3 
' Use a comma to as the decimal point (like they do in France and Spain). 
.lpDecimalSep = "," 
' Likewise, use a period as the grouping separator. 
.lpThousandSep = "." 
' Put the negative sign immediately after the number. 
-NegativeOrder = 3 

End With 

formatted = Space (256) 

strlen = GetNumberFormat (LOCALE USER DEFAULT, 0, "-1234567.89", nft, formatted, 

Len (formatted) ) 

formatted = Left(formatted, strlen) 

Debug.Print "Custom format: "; formatted 




































































See Also 


GetCurrencyFormat 





Category 


National Language Support 


Back to the Function list. 
Back to the Reference section. 








Last Modified: April 16, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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GetOpenFileName Function 








Declare Function GetOpenFileName Lib "comdlg32.d11" Alias "GetOpenFileNameA" (lpofn As 
OPENFILENAME) As Long 





























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetOpenFileName opens the Open File common dialog dialog box. All of the settings for creating the dialog, as well as the 
data returned from it, are placed into the structure passed as /pofn. Note that this function does not actually open any file; it 
merely prompts the user for a file or files to open, and those filenames are given to your program. 


Return Value 


If the user selects one or more files in the dialog box, the function returns a nonzero value. If an error occured, or if the user 
merely clicked Cancel, the function returns zero. Use CommDI]gExtendedError to get the error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpofn 
The parameters used to open the dialog box. Also receives the returned filename(s) and other information about what the 
user selected. 


Example 


Use the Open File common dialog box to prompt the user for a *.txt file. The user's selection is then displayed (the filename, not 
the file itself). The dialog box opens when the user clicks button Command 1. So, to use this example, place a command button 
named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 





" Declarations 
' (Copy them to 





and such needed 
the (declarations) 





Public Type OPE 


NEF TLENAME 











1Struct 
hwndOwn 
hinstan 





Size As Long 
er As Long 
ce As Long 





trFil 





ips 


ter As String 














lpstrCu 
nMaxCus 
nFilter 


lpstrFil 





stomFilter As String 
tomFilter As Long 


Index As Long 
e As String 





nMaxFil 


e As Long 














nMaxFi 


lpstrFil 
leTit] 


eTitle As String 
e As Long 





lpstrin 








itialDir As String 








lpstrTi 





tle As String 


flags As Long 














nFileof 
nFileEx 








fset As Integer 
tension As Integer 








lpstrDe 











fFExt As String 











1CustDa 
lpfnHoo 
lpTempl 

















End Type 


ta As Long 
k As Long 
ateName As String 








Public Const OF 








N_FILEMUSTEXIST = &H1000 











Public Const OF 
Public Const OF 
Publ Declare 











lic 
(lpofn 











N_HIDEREADONLY = &H4 
N_PATHMUSTEXIST = &H800 
Function GetOpenFileName 






































As OPEN 


FILENAME) 

















' **x*x Place the 


Private Sub 
Dim fil 
fna 
res 





Dim 





Dim 


" Confi 
With 





fi 


vbNullChar & _ 











vbNullChar 





As Long 





following code inside a 


Command1_Click () 








ebox As OPENFILENAME ' 
me As String i 
ult As Long : 














gure how the dialog box 

lebox 
" Size of 
-lStructSize = 
' Handle 
.-hwndOwner = 
' Handle 
-hinstance = 0 
' File 
-lpstrFilter = 














Me.hWnd 























"All Files 


for the examp 
section of 


open 





fi 7 


le: 
a module.) 





Lib "comdlg32.d11" Alias 








form window. 





ename the user 





result of opening 


the structure. 
Len (filebox) 
to window opening the dialog. 


to calling instance 


filters to make available: 
"Text Files 


(Ea KT 











ill look 


(not needed). 


(*.txt)" 


& vbNullChar & 


Wr x" 
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selected 
the dialog 


"GetOpenFileNameA" 


Text Files and All Files 
& voNullChar & 


"* txt" & 


& vbNullChar & 


Windows API Guide: GetOpenFileName Function 













































































', lpstrCustomFilter is ignored -- unused string 
.nMaxCustomFilter = 0 

' Default filter is the first one (Text Files, in this case). 
.nFilterIndex = 1 

' No default filename. Also make room for received 

' path and filename of the user's selection. 

-lpstrFile = Space(256) & vbNullChar 

-nMaxFile = Len(.lpstrFile) 

' Make room for filename of the user's selection. 
-lpstrFileTitle = Space(256) & vbNullChar 








-nMaxFileTitle = Len(.lpstrFileTitle) 
' Initial directory is C:\. 







































































.lpstrInitialDir = "C:\" & vbNullChar 

' Title of file dialog. 

.lpstrTitle = "Select a File" & vbNullChar 

' The path and file must exist; hide the read-only box. 

.flags = OFN_PATHMUSTEXIST Or OFN_FILEMUSTEXIST Or OFN_HIDEREADONLY 





















































' The rest of the options aren't needed. 
























































.nFileOffset = 0 

-nFileExtension = 0 

' lpstrDefExt is ignored -- unused string 
.lCustData = 0 

.lpfnHook = 0 

', lpTemplateName is ignored -- unused string 


End With 








' Display the dialog box. 
result = GetOpenFileName (filebox) 
If result <> 0 Then 
" Remove null space from the file name. 
fname = Left (filebox.lpstrFile, InStr(filebox.lpstrFile, vbNullChar) - 









































1) 








H- 








Debug.Print "The selected le: "; fname 





End If 











End Sub 





See Also 


GetSaveFileName 


Category 


Common Dialog 


Go back to the Function listing. 
Go back to the Reference section index. 








Last Modified: September 24, 2000 
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GetParent Function 


Declare Function GetParent Lib "user32.dll1" (ByVal hwnd As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 

GetParent returns the handle of the parent window of another window. For example, the parent of a button 
would normally be the form window it is in. If successful, the function returns a handle to the parent window. If 


it fails (for example, trying to find the parent of a non-window), it returns 0. 


hwnd 
The handle of the window to find the parent of. 


Example: 


' Figure out which frame, Framel or Frame2, the button Commandl 


' is located on -—- it is considered the child of the frame it is in 
Dim parenthwnd As Long ' button's parent window 
parenthwnd = GetParent (Commandl.hWnd) ' get the button's parent window 


If parenthwnd = Framel.hWnd Then Debug.Print "The button is inside Frame 1." 
If parenthwnd = Frame2.hWnd Then Debug.Print "The button is inside Frame 2." 


See Also: SetParent 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getparent.html 
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GetPixel Function 


Declare Function GetPixel Lib "gdi32.dll" (ByVal hdc As Long, ByVal nXPos 
As Long, ByVal nYPos As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetPixel determines the color of a specific pixel on a device. The function finds the RGB value of the pixel 
which is checked. 





Return Value 


If an error occured, the function returns & HFFFF. If successful, the function returns the RGB value of the 
pixel which was checked. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 
A handle to a device context to the device to check a pixel of. 


nXPos 
The x-coordinate of the pixel to determine the color of. 
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nYPos 
The y-coordinate of the pixel to determine the color of. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Fill all of window Forml with the color which is located at 








" coordinate (75,100). Fill the window by filling its rectangle using a 
' brush derived from the color of the pixel. 

Dim rgbVal As Long ' RGB color of the pixel 

Dim hBrush As Long ' handle to the brush we'll create 

Dim winrect As RECT ' rectangle of Forml 

Dim retval As Long ' return value 





" Determine the color of the pixel on Forml at (75,100). 
rgbVal = GetPixel(Forml.hDC, 75, 100) 








' Get the dimensions of the rectangle of window Forml. 
retval = GetWindowRect (Forml.hWnd, winrect) 








' Create a solid brush of that color. 

hBrush = CreateSolidBrush (rgbVal) 

' Use that brush to fill in all of Forml (its entire rectangle). 
retval = FillRect (Forml.hDC, winrect, hBrush) 

' Delete the brush we created to save resources. 

retval = DeleteObject (hBrush) 














See Also 


SetPixel, SetPixelV 





Category 


Bitmaps 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: September 2, 1999 
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GetPolyFillMode Function 


Declare Function GetPolyFillMode Lib "gdi32.d11" (ByVal hdc As Long) 
As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetPolyFillMode determines how a given device fills polygonal areas and shapes. These two modes 
only differ in how they handle complex overlapping polygons (i.e., polygons whose boundaries criss- 
cross themselves). The function returns 0 if an error occured, or exactly one of the following flags if 
successful: 


ALTERNATE = 1 
The device alternates between filling and not filling contiguous sections whose boundaries are 
determined by the edge(s) of the polygon crossing through the polygon's interior. 

WINDING = 2 
Any section inside the polygon is filled, regardless of any intra-polygonal boundaries and edges. 


hdc 
A device context to the device to find the polygon filling mode of. 


Example: 


' Display the current polygon fill mode of window Forml. 
Dim fillmode As Long ' receives fill mode 


fillmode = GetPolyFillMode (Forml.hDC) ' get the polygon fill mode 
If fillmode = ALTERNATE Then 
Debug.Print "Forml currently uses alternating filling." 
Else 
Debug.Print "Forml currently uses winding filling." 
End If 


See Also: SetPolyFillMode 
Category: Regions 
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Back to the index. 
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GetPrivateProfilelInt Function 


Declare Function GetPrivateProfileInt Lib "kernel32.d11" Alias 
"GetPrivateProfileIntA" (ByVal lpApplicationName As String, ByVal lpKeyName 
As String, ByVal nDefault As Long, ByVal lpFileName As String) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetPrivateProfileInt reads an integer value from any INI file. The parameters passed to the function specify 
which value will be read from. If successful, the function returns the value read. If the value you specify does 
not exist or is a string (i.e., not a number), the value specified as nDefault is returned. Note that INI file support 
is only provided in Windows for backwards compatibility; using the registry to store information is preferred. 


lpApplicationName 
The header of the INI file section the value is in. 
lpKeyName 
The name of the value to read. 
nDefault 
The value to return if a valid value cannot be read. Make it something that would definitely not be read, 
such as -1. 
lpFileName 
The filename of the INI file to read from. 


Example: 

' Read the "version" value under the "[programinfo]" section 

' of the INI file C:\MyProgram\config.ini 

Dim version As Long ' receives the value returned from the INI file 





" Read the value from the INI file, returning -1 if it can't find the value 
version = GetPrivateProfileInt ("programinfo", "version", -1, 
"C:\MyProgram\config.ini") 
' Display the result 
If version = -1 Then ' failure 
Debug.Print "Could not read the information from the INI file." 
Else 
Debug.Print "Version number:"; version 
End If 
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See Also: GetPrivateProfileString, GetProfileInt 
Category: INI Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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GetPrivateProfileString Function 








Declare Function GetPrivateProfileString Lib "kernel32.dll1" Alias 





WHITE | CLIFF 


"GetPrivateProfileStringA" (ByVal lpApplicationName As String, ByVal lpKeyName As 











Any, ByVal lpDefault As String, ByVal lpReturnedString As String, ByVal nSiz 
Long, ByVal lpFileName As String) As Long 




















Platforms: Win 32s, Win 95/98, Win NT 


e As 


GetPrivateProfileString reads an string value from an INI file. The parameters passed to the function specify which value 


will be read from. The function always returns the length in characters of the string put into the variable passed as 


lpReturnedString. If the function was successful, the string read from the INI file will be put into /pReturnedString. If not, it 
will instead receive the string given as /pDefault. Note that INI file support is only provided in Windows for backwards 


compatibility; using the registry to store information is preferred. 


[pApplicationName 

The header of the INI file section the value is in. 
IpKeyName 

The name of the value to read. 
[pDefault 


The value to return if a valid value cannot be read. Make it something that would definitely not be read, such as 


"(error)". 
[pReturnedString 

A fixed-length string that will receive either the string read from the file or JpDefault. 
nSize 

The length in characters of [pReturnedString. 
[pFileName 

The filename of the INI file to read from. 























Example: 

' Read the "username" value under the [default] section of 

' the INI file C:\MyProgram\config.ini. The default value is "anonymous". 
Dim uname As String ' receives the value read from the INI file 

Dim slength As Long ' receives length of the returned string 

uname = Space(255) ' provide enough room for the function to put the value 
buffer 

' Read from the INI file 

slength = GetPrivateProfileString ("default", "username", "anonymous", uname, 
"C:\MyProgram\config.ini") 

uname = Left (uname, slength) ' extract the returned string from the buffer 
Debug.Print "User's name: "; uname 
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See Also: GetPrivateProfileInt, GetProfileString, WritePrivateProfileString 
Category: INI Files 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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GetProfilelInt Function 


Declare Function GetProfileInt Lib "kernel32.d11" Alias "GetProfileIntA" (ByVal 
lpAppName As String, ByVal lpKeyName As String, ByVal nDefault As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Note: This function is primarily for backwards compatibility with 16-bit programs. 32-bit Windows programs should 
typically store data in the Registry instead. 


Description & Usage 


GetProfileInt reads an integer value from the WIN.INI file. The parameters passed to the function specify which 
value will be read from. This is basically a watered-down version of GetPrivateProfileInt because, unlike it, this 
function only works with WIN.INI. 


Return Value 


If successful, the function returns the integer value read from the INI file. If the specified key could not be found, the 
function returns the value passed as nDefault. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pAppName 
The header of the WIN.INI file section the value is in. 
IpKeyName 
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The name of the value to read. 

nDefault 
The value to return if a valid value cannot be read. This should typically be a default setting for the value, or 
something that would indicate that the value could not be read. 


Example 


Read the value "WallpaperStyle" from the [Desktop] section of the WIN.INI file and display it. To use this example, 
place a command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetProfileInt Lib "kernel32.d11" Alias "GetProfileIntA" 
(ByVal lpAppName _ 

As String, ByVal lpKeyName As String, ByVal nDefault As Long) As Long 


' xxx Place the following code inside the form window. *** 


Private Sub Commandl1_Click() 
Dim value As Long ' value read from WIN.INI 


" Read the desired value. 


value = GetProfileInt ("Desktop", "WallpaperStyle", -1) 
' Display the result. 
If value = -1 Then 
Debug.Print "Could not read the value!" 
Else 


Debug.Print "WallpaperStyle ="; value 
End If 
End Sub 


See Also 


GetPrivateProfileInt, GetProfileString 
Category 
INI Files 


Go back to the Function listing. 
Go back to the Reference section index. 
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GetRgnBox Function 


Declare Function GetRgnBox Lib "gdi32.dll1" (ByVal hRgn As Long, lpRect As 
RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetRgnBox determines the bounding rectangle of a given region. The bounding rectangle is the smallest possible 
rectangle which fully encompases the region. The bounding rectangle is placed in the structure passed as /pRect. 
The function returns 0 if an error occured, or exactly one of the following flags specifying the shape of the input 
region: 


COMPLEXREGION = 3 

The region is not empty but is not rectangular. 
NULLREGION = 1 

The region is empty, i.e., null. 
SIMPLEREGION = 2 

The region is rectangular in shape. 


hRgn 

A handle to the region to get the bounding rectangle of. 
lpRect 

Receives the coordinates of the region's bounding rectangle. 











Example: 

' Fill a triangular region on Forml in dark gray and fill its bounding 

' rectangle (behind it) in light gray. 

Dim triangle(0 To 2) As POINT TYPE ' vertices of triangular region 

Dim hRgn As Long ' handle to the triangular region 

Dim hLightBrush As Long, hDarkBrush As Long ' handles to the two brushes 
Dim bounding As RECT ' receives bounding rectangle of region 

Dim retval As Long ' generic return value 


' Create the triangular region. 








triangle(0).x = 150: triangle(0).y = 100 ' point #1: (150,100) 
triangle(1).x = 200: triangle(1).y = 150 ' point #2: (200,150) 
triangle(2).x = 175: triangle (2).y = 200 ' point #3: (175,200) 
hRgn = CreatePolygonRgn (triangle (0), 3, ALTERNATE) ' create the region 
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" Get handles to the light and dark gray solid stock brushes to use. 
hLightBrush = GetStockObject (LTGRAY_BRUSH) 
hDarkBrush = GetStockObject (DKGRAY_BRUSH) 








" Calculate the triangular region's bounding rectangle. 

retval = GetRgbBox(hRgn, bounding) " now bounding is the bounding rectangle 
' Fill the bounding rectangle in ligh gray, the region in dark gray. 

retval = FillRect (Form1l.hDC, bounding, hLightBrush) 

retval = FillRgn(Forml.hDC, hRgn, hDarkBrush) 


' Delete the region to free up resources. 
retval = DeleteObject (hRgn) 











Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/¢/getrgnbox.html 
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GetProfileString Function 


Declare Function GetProfileString Lib "kernel32.d1l1" Alias "GetProfileStringA" 
(ByVal lpAppName As String, ByVal lpKeyName As String, ByVal lpDefault As String, 
ByVal lpReturnedString As String, ByVal nSize As Long) As Long 


























Platforms: Win 32s, Win 95/98, Win NT 


GetProfileString reads an string value from the WIN.INI file. The parameters passed to the function specify which value 
will be read from. The function always returns the length in characters of the string put into the variable passed as 
[pReturnedString. If the function was successful, the string read from the INI file will be put into /pReturnedString. If not, it 
will instead receive the string given as /pDefault. This function is basically a watered-down version of 
GetPrivateProfileString because it, unlike this function, works with all INI files. Note that INI file support is only provided 


in Windows for backwards compatibility; using the registry to store information is preferred. 


lpAppName 
The header of the INI file section the value is in. 
IpKeyName 
The name of the value to read. 
lpDefault 
The value to return if a valid value cannot be read. Make it something that would definitely not be read, such as 
"(error)". 
lpReturnedString 
A fixed-length string that will receive either the string read from the file or /pDefault. 
nSize 
The length in characters of [pReturnedString. 


Example: 








' Read the value "Wallpaper" from under the [Desktop] section 
' of WIN.INI. f an error occurs, the function will return "(error)" 
Dim wallpaper As String ' receives string read from WIN.IN 
Dim slength As Long ' receives length of string read from WIN.IN 



























































wallpaper = Space(255) ' make room in the buffer to receive the string read from 
WIN.IN 
Read the string from WIN.IN 
slength = GetProfileString("Desktop", "Wallpaper", "(error)", buffer, 255) 






























































wallpaper = Left (wallpaper, slength) " extract the returned string from the buffer 
If wallpaper = "(error)" Then 

Debug.Print "Could not read information from WIN.INI." 
Else 

Debug.Print "Wallpaper file: "; wallpaper 
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End If 





See Also: GetPrivateProfileString, GetProfileInt, WriteProfileString 
Category: INI Files 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Go back to the Windows API Guide home page. 
E-mail: rogue953 @st-louis.crosswinds.net 


This page is at http://www.vbapi.com/ref/g/getprofilestring.html 
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GetProp Function 


Declare Function GetProp Lib "user32.dl11" Alias "GetPropA" (ByVal hWnd As Long, 
ByVal lpString As String) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetProp retrieves the value of one of the window properties of a window. The function obtains a handle to whatever 





object was associated with the window property. 


Return Value 


If successful, the function returns a handle to the object associated with the window property. If the desired window 
property could not be found, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 

A handle to the window to read a window property of. 
Ip String 

The name of the window property to read. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' Read the "LookupFile" property of window Forml and display it. 
' This property is set by the example for the SetProp function -- 
' the value is a string specifying a filename. 














Dim hData As Long, pData As Long ' handle and pointer to the property's data 
Dim strvalue As String ' receives the value of the window property (in this case) 
Dim retval As Long ' return value 








' Get a handle to the window property's data. 
hData = GetProp(Forml.hWnd, "LookupFile") 
' If that property didn't exist, alert the user. 
If hData = 0 Then 
Debug.Print "There is no property called 'LookupFile'." 
Else 
' Get a pointer to the data retrieved. 
pData = GlobalLock (hData) 
" Copy the string data into the string. 
























































strvalue = Space (lstrlen(pData) ) 
retval = lstrcpy(strvalue, pData) 
' Unlock the data block. 
retval = GlobalUnlock (hData) 
' Display the string gotten from the data block. 
Debug.Print "LookupFile = "; strvalue 
End If 


See Also 


SetProp 


Category 


Window Properties 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: December 24, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getprop.html 
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GetSaveFileName Function 








Declare Function GetSaveFileName Lib "comdlg32.d11" Alias "GetSaveFileNameA" (lpofn As 
OPENFILENAME) As Long 





























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetSaveFileName opens the Save File common dialog dialog box. All of the settings for creating the dialog, as well as the data 
returned from it, are placed into the structure passed as /pofn. Note that this function does not actually save any file; it merely 
prompts the user for a file to save, and that filename is given to your program. 


Return Value 


If the user selects a file in the dialog box, the function returns a nonzero value. If an error occured, or if the user merely clicked 
Cancel, the function returns zero. Use CommDIgExtendedError to get the error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpofn 
The parameters used to open the dialog box. Also receives the returned filename and other information about what the 
user selected. 


Example 


Use the Save File common dialog box to prompt the user for a *.txt file. The user's selection is then displayed (the filename, not 
the file itself). The dialog box opens when the user clicks button Command1. So, to use this example, place a command button 
named Command! on a form window. 
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' lpstrCustomFilter is ignored -- unused string 
.-nMaxCustomFilter = 0 

' Default filter is the first one (Text Files, in this case). 
.nFilterIndex = 1 

' No default filename. Also make room for received 

' path and filename of the user's selection. 

-lpstrFile = Space(256) & vbNullChar 

-nMaxFile = Len(.lpstrFile) 

' Make room for filename of the user's selection. 
-lpstrFileTitle = Space(256) & vbNullChar 








-nMaxFileTitle = Len(.lpstrFileTitle) 

' Initial directory is C:\. 

.lpstrInitialDir = "C:\" & vbNullChar 

' Title of file dialog. 

.lpstrTitle = "Select a File" & vbNullChar 

' The path must exist. Hide the read-only box. 

' Warn if an existing file is selected. 

.flags = OFN_PATHMUSTEXIST Or OFN_HIDEREADONLY Or OFN_OVERWRITEPROMPT 
' The rest of the options aren't needed. 

































































































































































-nFileOffset = 0 

-nFileExtension = 0 

' lpstrDefExt is ignored -- unused string 
.lCustData = 0 

.lpfnHook = 0 

', lpTemplateName is ignored -- unused string 


End With 








' Display the dialog box. 
result = GetSaveFileName (filebox) 
If result <> 0 Then 
" Remove null space from the file name. 
fname = Left (filebox.lpstrFile, InStr(filebox.lpstrFile, vbNullChar) - 


















































1) 





H- 














Debug.Print "The selected file: "; fname 











End Sub 





See Also 


GetOpenFileName 





Category 


Common Dialog 


Go back to the Function listing. 





Go back to the Reference section index. 
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Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getsavefilename.html 
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GetShortPathName Function 


Declare Function GetShortPathName Lib "kernel32.d11" Alias "GetShortPathNameA" (ByVal 
lpszLongPath As String, ByVal lpszShortPath As String, ByVal cchBuffer As Long) As 
Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetShortPathName converts a long filename into the old-style 8.3 filenames. Although Windows allows the use of long 
filenames, DOS programs and 16-bit Windows programs must use the 8.3 equivalent. For example, the equivalent of 
ReallyLongFile.txt could be REALLY~1.TXT. 


Return Value 


If successful, the function returns the length of the string copied into /pszShortPath, not including the terminating null 
character. If an error occured, the function returns 0 (use GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


lpszLongPath 
The complete long path and filename to convert. 
lpszShortPath 
Receives the 8.3 form of the filename, terminated by a null character. This string must already be sufficiently large to 
receive the 8.3 filename. 
cchBuffer 
The length of the string passed as /pszShortPath. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetShortPathName Lib "kernel32.d11" Alias "GetShortPathNameA" 




















ByVal lpszLongPath As String, ByVal lpszShortPath As String, ByVal cchBuffer 





~ 


As Long) As Long 





' Find the short filename equivalent of "C:\My Documents\ReadMeFirst.txt" 
Private Sub Command1_Click () 

Dim shortname As String ' receives short-filename equivalent 

Dim slength As Long ' receives length of short-filename equivalent 














' Make room in the buffer to receive the 8.3 form of the filename. 

shortname = Space (256) 

' Get the 8.3 form of the filename specified. 

slength = GetShortPathName ("C:\My Documents\ReadMeFirst.txt", shortname, 256) 




















' Remove the trailing null and display the result. 
shortname = Left (shortname, slength) 
Debug.Print "Equivalent: "; shortname 











End Sub 





See Also 


GetFullPathName 





Category 


Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: July 4, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getshortpathname.html 
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GetStockObject Function 


Declare Function GetStockObject Lib "gdi32.dll" (ByVal nIndex As Long) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


GetStockObject accesses one of Windows's stock pens, brushes, fonts, or palettes. This function provides fast access to these 
commonly used objects, instead of having to use more complicated functions. The function returns a handle to the pen, brush, 
font, or palette which the function accesses. Although the program isn't required to delete the handle using DeleteObject, doing 
so doesn't have any adverse effects. 


nIndex 
Exactly one of the following flags specifying which of the stock objects to create a handle to: 
ANSI_FIXED_FONT = 11 
The system's normal monospaced font. 
ANSI_VAR_FONT = 12 
The system's normal proportional-width font. 
BLACK_BRUSH = 4 
A solid black brush. 
BLACK_PEN =7 
A solid black pen. 
DEFAULT_GUI_FONT = 17 
Win 95/98 only: The default font for user objects under Windows. 
DEFAULT_PALETTE = 15 
The default system palette. 
DEVICE_DEFAULT_FONT = 14 
Win NT only: a device-dependent font. 
DKGRAY_BRUSH = 3 
A solid dark gray brush. 
GRAY_BRUSH = 2 
A solid gray brush. 
HOLLOW_BRUSH =5 
Same as NULL_BRUSH. 
LTGRAY_BRUSH = 1 
A solid light gray brush. 
NULL_BRUSH =5 
A null brush; i.e., a brush that does not draw anything on the device. 
NULL_PEN = 8 
A null pen; i.e., a pen that does not draw anything on the device. 
OEM_FIXED_FONT = 10 
The Original Equipment Manufacturer's default monospaced font. 
SYSTEM_FIXED_FONT = 16 
The system monospaced font under pre-3.x versions of Windows. 
SYSTEM_FONT = 13 
The system font (used for most system objects under Windows). 


http://216.26.168.92/vbapi/ref/g/getstockobject.html (1 of 2) [9/1/2002 5:27:58 PM] 


Windows API Guide: GetStockObject Function 


WHITE_BRUSH = 0 

A solid white brush. 
WHITE_PEN = 6 

A solid white pen. 


Example: 





' Draw a rectangle with a black border and light gray filled interior 














' on window Forml. Use stock pens and brushes to do this. 

Dim hbrush As Long, holdbrush As Long ' handles to stock brush & default brush 
Dim hpen As Long, holdpen As Long ' handles to stock pen & default pen 

Dim retval As Long ' return value 








' Load the stock pen and brush needed for this operation 


























hpen = GetStockObject (BLACK_PEN) ' load the black solid pen 

hbrush = GetStockObject (LTGRAY_BRUSH) ' load the light gray solid brush 

' Select the two objects in Forml and save the defaults 

holdpen = SelectObject (Form1l.hDC, hpen) " select the pen 

holdbrush = SelectObject (Forml.hDC, hbrush) ' select the brush 

' Draw the rectangle using the pen and brush. The rectangle has corners (20,25)- 
(200,175) 








retval = Rectangle(Forml.hDC, 20, 25, 200, 175) 

' Restore Forml's previously selected pen and brush 

retval = SelectObject (Form1l.hDC, holdpen) " reselect old pen 

retval = SelectObject (Forml.hDC, holdbrush) ' reselect old brush 

' Note that it is not necessary to delete hpen and hbrush, but we could if we wanted. 




















Category: Devices 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/g/getstockobject.html 
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GetSysColor Function 
Declare Function GetSysColor Lib "user32.dl11" (ByVal nIndex As Long) As Long 
Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetSysColor returns the RGB value of one of the system colors. The system colors are the ones Windows uses to draw the 
typical widgets in the graphical user interface. For example, this includes the colors of title bars, scroll bars, the desktop, 
window borders, etc. 


Return Value 


If successful, the function returns the RGB value of the requested system color. If an error occured, the function returns zero 
(use GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


nIndex 
One of the following flags specifying which system color to get: 
COLOR_3DDKSHADOW 
The dark shadow color for 3D objects. 
COLOR_3DFACE, COLOR_BTNFACE 
The face color for 3D objects. 
COLOR_3DHILIGHT, COLOR_3DHIGHLIGHT, COLOR_BTNHILIGHT, COLOR_BTNHIGHLIGHT 
The highlight (opposite of shadow) color for 3D objects. 
COLOR_3DLIGHT 
The light (opposite of shadow) color for 3D objects. 
COLOR_3DSHADOW, COLOR_BTNSHADOW 
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The shadow color for 3D objects. 
COLOR_ACTIVEBORDER 
The active window border color. 
COLOR_ACTIVECAPTION 
The active window title bar color. Windows 98, 2000: The color of the left side of the active window title bar 
gradient, if the gradient effect is used. 
COLOR_APPWORKSPACE 
The background color of multiple document interface (MDI) windows. 
COLOR_BACKGROUND, COLOR_DESKTOP 
The desktop color. 
COLOR_BTNTEXT 
The text color for pushbuttons. 
COLOR_CAPTIONTEXT 
The color of window caption text, size boxes, and scroll bar arrow boxes. 
COLOR_GRADIENTACTIVECAPTION 
Windows 98, 2000: The color of the right side of the active window title bar gradient, if the gradient effect is 
used. 
COLOR_GRADIENTINACTIVECAPTION 
Windows 98, 2000: The color of the right side of an inactive window's title bar gradient, if the gradient effect is 
used. 
COLOR_GRAYTEXT 
The color for disabled (grayed-out) text. 
COLOR_HIGHLIGHT 
The color used to highlight selected items. 
COLOR_HIGHLIGHTTEXT 
The color used for the text of highlighted items. 
COLOR_HOTLIGHT 
Windows 98, 2000: The color of a hot-tracked item, which is executed with a single click. 
COLOR_INACTIVEBORDER 
The color of an inactive window's border. 
COLOR_INACTIVECAPTION 
The color of an inactive window's caption. Windows 98, 2000: The color of the right side of an inactive 
window's title bar gradient, if the gradient effect is used. 
COLOR_INACTIVECAPTIONTEXT 
The color of an inactive window's caption text. 
COLOR_INFOBK 
The background color for tooltop controls. 
COLOR_INFOTEXT 
The text color for tooltip controls. 
COLOR_MENU 
The background color of menus. 
COLOR_MENUTEXT 
The color of menu text. 
COLOR_SCROLLBAR 
The color of a scroll bar's gray area. 
COLOR_WINDOW 
The background color of a window. 
COLOR_WINDOWFRAME 
The color of a window frame. 
COLOR_WINDOWTEXT 
The color of text in a window. 
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Windows API Guide: GetSysColor Function 
Constant Definitions 
Const COLOR_3DDKSHADOW = 21 
Const COLOR_3DFACE = COLOR_BTNFACE 
Const COLOR_3DHIGHLIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_3DHILIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_3DLIGHT = 22 
Const COLOR_3DSHADOW = COLOR_BTNSHADOW 
Const COLOR_ACTIVEBORDER = 10 
Const COLOR_ACTIVECAPTION = 2 
Const COLOR_APPWORKSPACE = 12 
Const COLOR_BACKGROUND = 1 
Const COLOR_BTNFACE = 15 
Const COLOR_BTNHIGHLIGHT = 20 
Const COLOR_BTN LIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_BTNSHADOW = 16 
Const COLOR_BTNTEXT = 18 
Const COLOR_CAPTIONTEXT = 9 
Const COLOR_DESKTOP = COLOR_BACKGROUND 
Const COLOR _GRADIENTACTIVECAPTION = 27 
Const COLOR_GRADIENTINACTIVECAPTION = 28 
Const COLOR_GRAYTEXT = 17 
Const COLOR_HIGHLIGHT = 13 
Const COLOR_HIGHLIGHTTEXT = 14 
Const COLOR_HOTLIGHT = 26 
Const COLOR_INACTIVEBORDER = 11 
Const COLOR_INACTIVECAPTION = 3 
Const COLOR_INACTIVECAPTIONTEXT = 19 
Const COLOR_INFOBK = 24 
Const COLOR_INFOTEXT = 23 
Const COLOR_MENU = 4 
Const COLOR_MENUTEXT = 7 
Const COLOR_SCROLLBAR = 0 
Const COLOR_WINDOW = 5 
Const COLOR_WINDOWFRAME = 6 
Const COLOR_WINDOWTEXT = 8 
Example 


Reverse the gradient colors in windows' title bars. In other words, the left-side gradient color is swapped with the right-side 
gradient color, for both active and inactive windows. Of course, this example won't work properly on Windows 95 or 
Windows NT 3.1 through 4.0, but you can still see how these two functions are used by looking at the source code. 


This example runs when the user clicks command button Command1. So, to use this example, you must first place a command 
button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
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Public Declare Funct 








Public Declare Function SetSysColors Lib 








lpaElements As Long, 
lpaRgbValues As Long) As Long 
Public Const COLOR_ACTIVECAPTION = 2 


Public C 
Public C 
Public C 








onst COLOR_ 


GRADIENTACTIVECAPTION 











onst COLOR_ 
onst COLOR_ 























tion GetSysColor Lib "user32.dll1" (ByVal nIndex As Long) As Long 





"user32.dl 














= 27 


GRADIENTINACTIVECAPTION = 28 














INACTIVECAPTION = 3 








' xxx Place the following code inside a 


Private 





Sub Commandi1_Click () 
Dim activeLeftColor As Long 








window t 


O H- 


tle bar 








window t 


tle bar 


O e-e- 








window t 


inactive 


End Sub 








tle bar 


O H- 








im activeRightColor As Long 





im inactiveLeftColor As Long 


im inactiveRightColor As Long 
window title bar 
im colorNames(0 To 3) As Long 




















im retval 


im colorRGBs(0 To 3) As Long 


As Long 














form window. 





1" ( 


ByVal cElements As Long, 


KkK* 


left-side gradient of active 





' Color of 





" color of 





right-side gradient of active 





the left-side gradient of inactive 


the right-side gradient of 


' identifiers of the system colors to change 





" RGB values of 





f the system colors to change 


' generic return value 


' Get the RGB values of the colors used in title bars. 


activeLeftColor = GetSysColor (COLOR_ACTIV 
activeRightColor = GetSysColor (COLOR_GRAD 








inactiveLei 





























fFtColor = GetSysColor (COLOR_ 
inactiveRightColor = GetSysColor (COLOR_GRA 











ECAPTION) 




















ENTACTIVECAPTION) 








NAC’ 





TIVECAPTION) 







































































DIENTINACTIVECAPTION) 





























Note how we're switching 





' Load the arrays with the new values to assign. 

" the values used on the left and right sides of the two gradients. 
colorNames (0) = COLOR_ACTIVECAPTION 

colorRGBs (0) = activeRightColor 

colorNames (1) = COLOR_GRADIENTACTIVECAPTION 

colorRGBs(1) = activeLeftColor 

colorNames (2) = COLOR_INACTIVECAPTION 

colorRGBs(2) = inactiveRightColor 

colorNames (3) = COLOR_GRADIENTINACTIVECAPTION 

colorRGBs (3) = inactiveLeftColor 











' Change the system color settings as specified above. 


retval = SetSysColors (4, 





See Also 


SetSysColors 


colorNames (0), 
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Category 


System Information 


Back to the Function list. 
Back to the Reference section. 








Last Modified: September 24, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getsyscolor.html 
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GetSystemDirectory Function 











Declare Function GetSystemDirectory Lib "kernel32.dll1" Alias "GetSystemDirectoryA" 
(ByVal lpBuffer As String, ByVal nSize As Long) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


GetSystemDirectory reads the path of Windows's System directory. This is where many important files for Windows are 
stored, including the API DLLs. Never assume this is "C:\Windows\System" because the Windows directory doesn't have 
to be called Windows. The path of the system directory is put into the string variable passed as [pBuffer. The function 
returns the length of the string returned if it is successful, or 0 if it failed. 


lpBuffer 

A string which receives the path of the system directory. 
nSize 

The length in characters of lpBuffer. 














Example: 

' Display the path of the system directory 

Dim sysdir As String ' receives path of system directory 

Dim slength As Long ' receives length of returned string 

sysdir = Space (255) ' make room in the buffer to receive the string 

slength = GetSystemDirectory(sysdir, 255) ' determine the system directory's path 
sysdir = Left(sysdir, slength) ' extract the returned string from the buffer 








Debug.Print "System directory path: "; sysdir 


See Also: GetWindowsDirectory 
Category: System Information 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getsystemdirectory.html 
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GetSystemMenu Function 
Declare Function GetSystemMenu Lib "user32.dl1" (ByVal hWnd As Long, ByVal bRevert As 














Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetSystemMenu obtains a handle to a window's system menu (also known as its control menu). This menu is what appears 
when the application icon on the title bar is clicked, or when the title bar itself is right-clicked. Once you get a handle to a 
window's system menu, you can use the other menu functions to add or remove items from it. However, note that all items on a 
system menu send the WM_SYSCOMMAND message to the parent window instead of the usual WM_COMMAND message. 
Alternately, GetSystemMenu could also be used to restore the system menu to its default appearance, removing any 
modifications done to it. 














Return Value 


If the bRevert parameter is zero, GetSystemMenu returns a handle to the window's system menu. If bRevert is nonzero, this 
function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to locate the system menu of. 

bRevert 
If zero, the function obtains a handle to the window's system menu. If nonzero, the function instead reverts the system 
menu back to its default appearance. 
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Example 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 


' (Copy them 


' There 
ublic 


oO tv 


AG) 


ublic 
Long 
ublic 





AG) 





Public 
Public 
Public 
Public 
Public 
Public 
Public 
P 
( 





ublic 





tg 


ublic 





~ 


Public 





ByVal _ 


to the 











's quite a 





As Long) 





(declarations) 


few declarations 


As Long 
Declare Function GetMenuItemCount Lib 


section of 
for this example, 
Declare Function GetSystemMenu Lib "user32.d1ll1" ( 
Revert _ 











Type MENUITEMINFO 














cbSize As Long 











wID As Long 





fMask As Long 
fType As Long 
fState As Long 


hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 








cch As Long 


End Type 





Con 
Con 





IIM_ID 


IIM_STATE = 


&H1 





= &H2 











Con 


IIM_TYPE = 


&H10 





Con 
Con 


FT_SEPARATOR = 
FT_STRING = 


&H800 





&HO 





T Ss Ss = 15 1S 


S 
S 
S 
st 
S 
S 





Con 





BLED = &HO 





FS_ENA 




















Const MFS_CHECKED = &H8 


























ByVal _ 
hMenu As Long, 


Declare Function InsertMenuItem Lib 














As MENUITEMINFO) 








As Long 








ByVal _ 
hMenu As Long, 


Declare Function SetMenuItemInfo Lib 


ByVal uItem As Long, 














As MENUITEMINFO) 








As Long 








hWndinsertAf 


ter As Long, 


Declare Function SetWindowPos Lib 


ByVal ulItem As Long, 











cy As Long, 





Public Const 
Public Const 
Public Const 
Public Const 
Public 
hWnd _ 























ByVal wFlags As Long) 
WND_TOPMOST = -1 

WND_NOTOPMOST = -2 
SWP_NOMOV] 
SWP_NOSIZI 
Declare Function 





= &H2 
= &H1 








m 
Pi 
m 
Di 








ByVal x As Long, 


SetWindowLong Lib 








a module.) 





ByVal 





"user32.dll 


"user32.d11" 





ns and conditions listed here. 


but it's worth it! 
hWnd As Long, 





ByVal 


" (ByVal hMenu As Long) As 


Alias 














ByVal fByPosition As Long, 





"user32.d11" 


Alias 

















"user32.dll1" (ByVal 


ByVal fByPosition As Long, 








As Long 


"user32.dl1" 
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Alias 


ByVal y As Long, 


hWnd As Long, 


"SetMenultemIini 


"InsertMenulItemA" 


lpmii _ 


FOA" 











"SetWindowLongA" 


lpmii _ 


ByVal _ 
ByVal cx As Long, 





(ByVal 


Windows API Guide: GetSystemMenu Function 








As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 
ublic Const GWL_WNDPROC = -4 
ublic Declare Function CallWindowProc Lib "user32.d1l1" Alias "CallWindowProcA" 
ByVal 


tg 





tg 














— 











lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 

Public Const WM SYSCOMMAND = &H112 

Public Const WM INITMENU = &H116 




















' Add an option to make window Forml "Always On Top" to the bottom of its system 




















' menu. A check mark appears next to this option when active. The menu item acts as 
a toggle. 

' Note how subclassing the window is necessary to process the two messages needed 

' to give the added system menu item its full functionality. 

' *** Place the following code in a module. *** 


Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public ontop As Boolean ' identifies if Forml is always on top or not 

















' The following function acts as Forml's window procedure to process messages. 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 









































As Long, ByVal lParam As Long) As Long 
Dim hSysMenu As Long ' handle to Forml's system menu 
Dim mii As MENUITEMINFO ' menu item information for Always On Top 
Dim retval As Long ' return value 


Select Case uMsg 

Case WM INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 



















































































With mii 
' Size of the structure. 
.cbSize = Len(mii) 
' Only use what needs to be changed. 
.£fMask = MIIM_ STATE 
' If Forml is now always on top, check the item. 
.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenultemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 


Case WM SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 











top 





' setting of Forml to match. 
If wParam = 1 Then 
' Reverse the setting and make it the current one. 
ontop = Not ontop 
retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 
































HWND_NOTOPMOST), 





0, 0, 0, 0, SWP_NOMOVE Or SWP_NOSTIZI 








CI 
Sis 
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procedure 
lParam) 

Case 
it. 








' *** Place the 





Else 


End 
Else 








' Tf this is som 


Wind 


End Select 
End Function 





' When Forml loads, 


" new win 
Private S 








hSysMenu 





ub 


Dim 


im 


Dim 


im 


Form_Loa 
hSysMenu 
count As 
mii As M 


WindowProc 


" Some other item was selected. 


0 





Let the previous window 


' process it. 
WindowProc 


Tf 


OwProc 


CallWindowProc(pOldProc, hwnd, uMsg, wParam, 








CallWindowProc(pOldProc, 


other message, 


let the previous procedure handle 


hwnd, uMsg, wParam, lParam) 





following code inside Forml. 


KK* 


add Always On Top to the system menu and set up the 
dow procedure. 


d () 
As Long 
Long 











ENUITEMIN 





PO 





retval A 


s Long 


handle to the system menu 
the number of items initially on the menu 
describes a menu item to add 


return value 


Get a handle to the system menu. 


GetSystemMenu (Forml.hWnd, 


0) 


See how many items are currently in it. 
count = GetMenuItemCount (hSysMenu) 


Add a separator bar and then Always 


























On Top to the system menu. 

















With mii 
' The size of the structure. 
.cbSize = Len (mii) 
' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 
.£Type = MFT_SEPARATOR 
' It has an ID of 0. 
-wID = 0 
End With 
' Add the separator to the end of the system menu. 


retval 


InsertMen 











Likewise, 
With mii 


.£Ma 
Th 





add th 


.fType 





M 


sk 
is is 


I 
a 








M 


IM_STATE 
regular 
FT_STRING 
' The option is enabled. 


T 





ultem(hSysMenu, 








.£S 
» ob 





tate 


has an II 


= MFS 





ENA 





BL 


G 





iD 











D of 


1 


count, 1, mii) 


e Always On Top command. 


Or MIIM_ID Or MIIM_TYPE 
text item. 











(this identifies it in the window procedure). 
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.wID = 1 
' The text to place in the menu item. 
.dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenulItem(hSysMenu, count + 1, 1, mii) 





' Set the custom window procedure to process Forml's messages. 
ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 


End Sub 




















' Before unloading, restore the default system menu and remove the 
' custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














' Replace the previous window procedure to prevent crashing. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
' Remove the modifications made to the system menu. 
retval = GetSystemMenu (Forml.hWnd, 1) 
End Sub 




















See Also 


GetMenu 


Category 


Menus 


Back to the Function list. 
Back to the Reference section. 








Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/g/getsystemmenu.html 
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GetSystemMetrics Function 








Declare Function GetSystemMetrics Lib "user32.dll1" (ByVal nIndex As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GetSystemMetrics returns information about various things in Windows. Most of these deal with the sizes of various 
objects, such as the screen, icons, cursors, etc. This function provides information about the system. The return value of the 
function depends on the value specified for nJndex. Keep in mind that all sizes (such as widths and heights) are measured in 
pixels. Also note that some of the metrics have slightly different meanings between Win NT and Win 95/98. 


nIndex 
Exactly one of the following flags specifying which piece of information to return: 
SM_ARRANGE = 56 
Win 95/98 only: Return the method used to display minimized windows. The return value is a combination 
of two of the following flags, one specifying a starting position for the minimized icons and another 
specifying the direction in which new ones are added: 
ARW_BOTTOMLEFT = 0 
Start placing the icons in the bottom-left corner of the screen. 
ARW_BOTTOMRIGHT = 1 
Start placing the icons in the bottom-right corner of the screen. 
ARW_DOWN = 4 
Add new icons below existing ones. 


ARW_HIDE = 8 
Do not place the icons anywhere on the screen (i.e., hide them). 
ARW_LEFT = 0 


Add new icons to the left of existing ones. 
ARW_RIGHT = 4 
Add new icons to the right of existing ones. 
ARW_STARTRIGHT = 1 
Same as ARW_BOTTOMRIGHT. 
ARW_STARTTOP = 2 
Same as ARW_TOPLEFT. 
ARW_TOPLEFT = 2 
Start placing the icons in the top-left corner of the screen. 
ARW_TOPRIGHT = 3 
Start placing the icons in the top-right corner of the screen. 
ARW_UP =0 
Add new icons above existing ones. 
SM_CLEANBOOT = 67 
Win 95/98 only: Return a value specifying how the computer was booted up. 0 means a normal bootup, 1 
means a fail-safe (a.k.a. SafeBoot) bootup, and 2 means a fail-safe bootup with the network installed. 
SM_CMETRICS = 44 
Win 95/98 only: Return the number of system metrics. 
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SM_CMOUSEBUTTONS = 43 

Return the number of mouse buttons on the installed mouse, or 0 if no mouse is installed. 
SM_CXBORDER = 5 

Win NT: Return the width of a window border. Win 95/98: Return the width of a single window border. 
SM_CXCURSOR = 13 

Win NT: Return the width of the cursor. Win 95/98: Return the width of the standard cursor bitmap. 
SM_CXDLGFRAME = 7 

Win NT only: Return the width of a window frame having a dialog frame style. 
SM_CXDOUBLECLK = 36 

The width of the rectangle within which both mouse clicks must be to recognize a double-click. 
SM_CXDRAG = 68 

Return the minimum width the cursor must move to begin a drag-and-drop operation. 
SM_CXEDGE = 45 

Win 95/98 only: Return the width of a 3D window border. 
SM_CXFRAME = 32 

Win NT only: Return the width of the border of a resizable window. 
SM_CXFULLSCREEN = 16 

Return the width of the client area of a full-screen window. 
SM_CXHSCROLL = 21 

Win 95/98 only: Return the width of an arrow bitmap on a horizontal scrollbar. 
SM_CXHTHUMB = 10 

Return the width of the horizontal scrollbar thumb. 
SM_CXICON = 11 

Return the default width of an icon. 
SM_CXICONSPACING = 38 

Win NT: Return the width of the cell used to position icons. Win 95/98: Return the width of the grid cell for 

items in a large icon view. 
SM_CXMAXIMIZED = 61 

Win 95/98 only: Return the default width of a maximized window. 
SM_CXMAXTRACK = 59 

Win 95/98 only: Return the default maximum width the user is allowed to resize a window to. 
SM_CXMENUCHECK = 71 

Win 95/98 only: Return the width of the default menu check-mark bitmap. 
SM_CXMENUSIZE = 54 

Win 95/98 only: Return the width of a menu bar button. 
SM_CXMIN = 28 

Return the minimum width of a window. 
SM_CXMINIMIZED = 57 

Win 95/98 only: Return the width of a normal minimized window. 
SM_CXMINSPACING = 47 

Win 95/98 only: Return the width of the grid cell rectangle used to position minimized windows. 
SM_CXMINTRACK = 34 

Win 95/98 only: Return the default minimum width the user is allowed to resizea window to. 
SM_CXSCREEN = 0 

Return the width of the screen. 
SM_CXSIZE = 30 

Win NT: Return the width of a title bar bitmap. Win 95/98: Return the width of a caption button. 
SM_CXSIZEFRAME = 32 

Win 95/98 only: Return the width of a thick window frame. 
SM_CXSMICON = 49 

Win 95/98 only: Return the recommended width for small icons. 
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SM_CXSMSIZE = 52 

Win 95/98 only: Return the width of a small caption button. 
SM_CXVSCROLL = 2 

Win 95/98 only: Return the width of a vertical scrollbar. 
SM_CYBORDER = 6 


Win NT: Return the height of a window border. Win 95/98: Return the height of a single window border. 


SM_CYCAPTION = 4 

Return the height of a normal caption area. 
SM_CYCURSOR = 14 

Win NT: Return the height of the cursor. Win 95/98: Return the height of the standard cursor bitmap. 
SM_CYDLGFRAME = 8 

Win NT only: Return the height of a window frame having a dialog frame style. 
SM_CYDOUBLECLK = 37 

Return the height of the rectangle within which both mouse clicks must be to recognize a double-click. 
SM_CYDRAG = 69 

Return the minimum height the cursor must move to begin a drag-and-drop operation. 
SM_CYEDGE = 46 

Win 95/98 only: Return the height of a 3D window border. 
SM_CYFRAME = 33 

Win NT only: Return the height of the border of a resizable window. 
SM_CYFULLSCREEN = 17 

Return the height of the client area of a full-screen window. 
SM_CYHSCROLL = 3 

Win 95/98 only: Return the height of a horizontal scrollbar. 
SM_CYICON = 12 

Return the default height of an icon. 
SM_CYICONSPACING = 39 


Win NT: Return the height of the cell used to position icons. Win 95/98: Return the height of the grid cell 


for items in a large icon view. 
SM_CYKANJIWINDOW = 18 

Return the height of the Kanji window (for double-byte character set versions of Windows). 
SM_CYMAXIMIZED = 62 

Win 95/98 only: Return the default height of a maximized window. 
SM_CYMAXTRACK = 60 

Win 95/98 only: Return the default maximum height the user is allowed to resize a window to. 
SM_CYMENU = 15 

Return the height of a single menu bar. 
SM_CYMENUCHECK = 72 

Win 95/98 only: Return the height of the default menu check-mark bitmap. 
SM_CYMENUSIZE = 55 

Win 95/98 only: Return the height of a menu bar button. 
SM_CYMIN = 29 

Return the minimum height of a window. 
SM_CYMINIMIZED = 58 

Win 95/98 only: Return the height of a normal minimized window. 
SM_CYMINSPACING = 48 

Win 95/98 only: Return the height of the grid cell rectangle used to position minimized windows. 
SM_CYMINTRACK = 35 

Win 95/98 only: Return the default minimum height the user is allowed to resize a window to. 
SM_CYSCREEN = 1 

Return the height of the screen. 
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SM_CYSIZE = 31 

Win NT: Return the height of a title bar bitmap. Win 95/98: Return the height of a caption button. 
SM_CYSIZEFRAME = 33 

Win 95/98 only: Return the height of a thick window frame. 
SM_CYSMCAPTION = 51 

Win 95/98 only: Return the height of a small caption area. 
SM_CYSMICON = 50 

Win 95/98 only: Return the recommended height for small icons. 
SM_CYSMSIZE = 53 

Win 95/98 only: Return the height of a small caption button. 
SM_CYVSCROLL = 20 

Win 95/98 only: Return the height of an arrow bitmap on a vertical scrollbar. 
SM_CYVTHUMB = 9 

Return the height of a vertical scrollbar thumb. 
SM_DBCSENABLED = 42 

Return a non-zero value if the double-byte character set version of USER.EXE is installed, 0 if not. 
SM_DEBUG = 22 

Return a non-zero value if the debugging version of USER.EXE is installed, 0 if not. 
SM_MENUDROPALIGNMENT = 40 

Return a non-zero value if popup menus appear to the right, 0 if to the left. 
SM_MIDEASTENABLED = 74 

Return a non-zero value if the system is enabled to use Hebrew and Arabic languages, 0 if not. 
SM_MOUSEPRESENT = 19 

Return a non-zero value if a mouse is installed and present, 0 if not. 
SM_NETWORK = 63 

Set the &H1 bit of the return value if a network is installed. All other bits of the return value are reserved and 

undefined. 
SM_PENWINDOWS = 41 

Return a non-zero value if the Microsoft Windows for Pen computing extensions are installed, 0 if not. 
SM_SECURE = 44 

Return a non-zero value if security is present and active, 0 if not. 
SM_SHOWSOUNDS = 70 

Return a non-zero value if the application should show a visual cue for all sounds, 0 if not. 
SM_SLOWMACHINE = 73 

Return a non-zero value if the system has a slow, low-end processor, 0 if not. 
SM_SWAPBUTTON = 23 

Return a non-zero value if the left and right mouse buttons are swapped, 0 if not. 

















Example: 

' Display the screen resolution (size) and some information about the 

' configuration of windows. 

Dim xres As Long, yres As Long ' receive x and y resolutions of the display 

Dim hasmouse As Long, numbuttons As Long ' receive presense of mouse and number of 
buttons 

Dim hasnetwork As Long ' receives info on availability of network 

' Display the screen resolution -- i.e., the width and height of the screen. 

xres = GetSystemMetrics (SM_CXSCREEN) 


yres 





= GetSystemMetrics (SM_CYSCREEN) 


Debug.Print "The display is"; xres; "pixels wide and"; yres; "pixels high." 
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' Display the number of buttons on the mouse, if a mouse is present. 
hasmouse = GetSystemMetrics (SM _MOUSEPRESENT) 
numbuttons = GetSystemMetrics (SM_CMOUSEBUTTONS) 





If hasmouse = 0 Then 
Debug.Print "No mouse is installed on the system." 
Else 





Debug.Print "A mouse with"; numbuttons; "buttons is installed." 
End If 








' Display whether the system has a network connection installed. 
hasnetwork = GetSystemMetrics (SM_NETWORK) 

If (hasnetwork And &H1) = &H1 Then ' check only the information bit 
Debug.Print "A network is configured to be used by Windows." 

Else 

Debug.Print "No network is currently configured." 

End If 




















See Also: SystemParametersInfo 
Category: Accessibility 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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GetSystemTime Function 


Declare Sub GetSystemTime Lib "kernel32.d1l1" (lpSystemTime As SYSTEMTIME) 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetSystemTime retrieves the current system date and time and places it into a SYSTEMTIME structure. 
Times are always reported in UTC time (Coordinated Universal Time, a.k.a. Greenwich Mean Time (GMT)), 
not in the system's local time. 


Return Value 


GetSystemTime does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpSystemTime 
Receives the current system date and time. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Display the current time in UTC time (along the Prime Meridian). 





Dim utctime As SYSTEMTIMFE ' receives time and date 

GetSystemTime utctime ' put the time and date in UTC time into utctime 
Debug.Print "In Greenwich, England, the time is"; utctime.wHour; ":"; 
utctime.wMinute; ":"; utctime.wSecond 


GetLocalTime, GetSystemTimeAsFileTime, SetSystemTime 


Category 


Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetSystemTimeAsFileTime Function 


Declare Sub GetSystemTimeAsFileTime Lib "kernel32.d11" 
(lpSystemTimeAsFileTime As FILETIME) 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetSystemTimeAsFileTime retrieves the current system date and time and places it into a FILETIME 


structure. The system time is always reported in UTC time (Coordinated Universal Time, a.k.a. Greenwich 
Mean Time (GMT)). 


Return Value 


GetSystemTimeAsFileTime does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpSystemTimeAsFileTime 
Receives the current system date and time. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Set the modification time of C:\MyApp\test.txt to 














" the current system date and time. Leave the other times as they 
" were before calling the function. 

Dim hFile As Long ' handle to the opened file 

Dim ctime As FILETIME ' the time of creation 

Dim atime As FILETIME ' the time of last access 

Dim mtime As FILETIME ' the time of last modification 

Dim retval As Long ' return value 








' First, open the file C:\MyApp\test.txt for both read-level and 

' write-level access, since we need to do both. 

hFile = CreateFile("C:\MyApp\test.txt", GENERIC_READ Or GENERIC_WRITE, 
FILE SHARE READ, ByVal CLng(0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0) 
If hFile = -1 Then 























Debug.Print "Could not open the file successfully -- aborting." 
End ' terminate the program 
End If 





" Next, get the creation, last-access, and last-modification times. 
retval = GetFileTime(hFile, ctime, atime, mtime) 





' Get the system time (already in UTC) as a FILETIME structure. 
GetSystemTimeAsFileTime mtime 

' Set the retrieved creation and access times and the new modification 
" time as the file's times. 

retval = SetFileTime(hFile, ctime, atime, mtime) 











" Close the file to free up resources. 
retval = CloseHandle (hFile) 





See Also 


GetSystemTime 


Category 


Time 


Go back to the alphabetical Function listing. 
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Go back to the Reference section index. 
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GetTempFileName Function 





























Declare Function GetTempFileName Lib "kernel32.d11" Alias "GetTempFileNameA" (ByVal 
lpszPath As String, ByVal lpPrefixString As String, ByVal wUnique As Long, ByVal 
lpTempFileName As String) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetTempFileName generates a filename for a temporary file and optionally creates it for you. Temporary files are used to 
store data for short periods of time on the hard drive. The full filename, including the path, is put into the string variable passed 
as IpTempFileName. The format of the generated filename is path\xxxuuuu.TMP. path is the path to put the file in, preferably 
the temporary directory supplied by Windows, which can be gotten through GetTempPath. xxx is the string specified in 
IpPrefixString. wuuu is a hexadecimal number between 0000 and FFFF. If wUnique is non-zero, uuuu is the rightmost four 
digits of the number (in hexadecimal), and the file is not created. This method will work even if a file with that name already 
exists. If wUnique is zero, uuuu is a random number generated by Windows, and the file is created. Temporary files always 
have a .TMP extension. The function returns the value used for uuuu if successful, or 0 if an error occured. 


IpszPath 

The path to put the temporary file into. This is preferably the same path gotten from GetTempPath. 
lpPrefixString 

The first three characters of the filename. 
wUnique 


If non-zero, this number's last four digits in hexidecimal are the last four characters in the filename, and the file is not 
created. If zero, the last four characters are generated by Windows, and the file is created. 

lpTempFileName 
A string that receives the path and filename of the temporary file. 


Example: 


' Generate a temporary file where (path) 
' is Windows's temporary file directory and ???? is a randomly assigned unique value. 













































































' Then display the name of the created file on the screen. 

Dim temppath As String ' receives name of temporary file path 

Dim tempfile As String ' receives name of temporary file 

Dim slength As Long ' receives length of string returned for the path 
Dim lastfour As Long ' receives hex value of the randomly assigned ???? 
' Get Windows's temporary file path 

temppath = Space (255) ' initialize the buffer to receive the path 
slength = GetTempPath(255, temppath) ' read the path name 

temppath = Left (temppath, slength) ' extract data from the variable 


' Get a uniquely assigned random file 


E 


tempf 
lastfour 





ile = 


Space (255) l 


GetTempFileName (temppath, 


LV 





e the filename 





initialize buffer to rec 
"api", 0, tempf 
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get a unique temporary 


Windows API Guide: GetTempFileName Function 


file name 
' (Note that the file is also created for you in this case.) 





tempfile = Left (tempfile, InStr(tempfile, vbNullChar) - 1) ' extract data from the 
variable 
Debug.Print "Temporary filename: "; tempfile 





See Also: GetTempPath 
Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Go back to the Windows API Guide home page. 
E-mail: rogue953 @st-louis.crosswinds.net 


This page is at http://www.vbapi.com/ref/g/gettempfilename.html 
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GetTempPath Function 


Declare Function GetTempPath Lib "kernel32.d1ll1" Alias "GetTempPathA" (ByVal 
nBufferLength As Long, ByVal lpBuffer As String) As Long 





























Platforms: Win 32s, Win 95/98, Win NT 


GetTempPath determines Windows's default Temp directory. The Temp directory is where temporary files made and used by 
Windows-based programs should be put. Usually this will be the \Temp subdirectory under the Windows directory, but not 
necessarily. The path of the directory is put into the string variable passed as /pBuffer. The function returns the length of the 
string returned by the function if it succeeds, or 0 if it fails. 


nBufferLength 
The length in characters of lpBuffer 
lpBuffer 
A string that will receive the path of the Temp directory. 


Example: 


' Generate a temporary file (path)\api????.TMP, where (path) 





cay 







































































' is Windows's temporary file directory and ???? is a randomly assigned unique value. 
' Then display the name of the created file on the screen. 

Dim temppath As String ' receives name of temporary file path 

Dim tempfile As String ' receives name of temporary file 

Dim slength As Long ' receives length of string returned for the path 

Dim lastfour As Long ' receives hex value of the randomly assigned ???? 

' Get Windows's temporary file path 

temppath = Space (255) ' initialize the buffer to receive the path 

slength = GetTempPath (255, temppath) ' read the path name 

temppath = Left (temppath, slength) ' extract data from the variable 


' Get a uniquely assigned random file 


tempfile = Space (255) ' initialize buffer to receive the filename 
lastfour = GetTempFileName(temppath, "api", 0, tempfile) ' get a unique temporary 




















file name 





E 





























' (Note that the file is also created for you in this case.) 

tempfile Left (tempfile, InStr(tempfile, vbNullChar) - 1) ' extract data from the 
variable 

Debug.Print "Temporary filename: "; tempfile 








See Also: GetTempFileName 
Category: System Information 
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Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





Go back to the Windows API Guide home page. 


E-mail: rogue953 @st-louis.crosswinds.net 
This page is at http://www.vbapi.com/ref/g/gettemppath.html 
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GetTextAlign Function 


Declare Function GetTextAlign Lib "gdi32.d1ll" (ByVal hdc As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 








GetTextAlign determines how a device displays a line of text relative to a given reference point. The reference point is the 

point used to specify where the device should display a line of text. The function returns exactly three of the following flags 
specifying where this reference point will be relative to the text (one flag specifies horizontal position, one specifies vertical 
position, one determines current point updating): 


TA_BASELINE = 24 
The reference point will be on the baseline of the text. 


TA_BOTTOM = 8 


The reference point will be on the bottom edge of the bounding rectangle of the text. 


TA_CENTER = 6 


The reference point will be horizontally centered along the bounding rectangle of the text. 


TA_LEFT = 0 


The reference point will be on the left edge of the bounding rectangle of the text. 


TA_NOUPDATECP 


=0 


Do not set the current point to the reference point. 


TA_RIGHT = 2 


The reference point will be on the right edge of the bounding rectangle of the text. 


TA_RTLREADING 


= 256 


Win 95/98 only:Display the text right-to-left (if the font is designed for right-to-left reading). 


TA_TOP =0 


The reference point will be on the top edge of the bounding rectangle of the text. 


TA_UPDATECP = 1 


Set the current point to the reference point. 


hdc 


The device context of the device to find the reference point settings of. 


Example: 





' Display whether window Form] 


will display text left-—justified, 











' centered, or right-justified relative to a given reference point. 























Dim refpoint As Long ' receives reference point settings 
refpoint = GetTextAlign (Forml1.hDC) " get the text alignment setting of the window 
If (refpoint And TA_RIGHT) = TA_RIGHT Then t ref. point on right edge 
Debug.Print "Text will be displayed right-—justified." 
ElseIf (refpoint And TA_CENTER) = TA_CENTER Then ' ref. point horizontally centered 
Debug.Print "Text will be displayed centered horizontally." 
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Else ' assume ref. point on left edge 
Debug.Print "Text will be displayed left-justified." 
End If 





See Also: SetTextAlign, TextOut 
Category: Fonts & Text 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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GetThreadLocale Function 
Declare Function GetThreadLocale Lib "kernel32.dll1" () As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetThreadLocale identifies the locale of the thread which called the function (i.e., your program's thread). This locale 
determines the default preferences for display of various data for the program and may be different than that of other threads. 





Return Value 


The function returns the identifier of the calling thread's locale. 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Use a case-senitive, string sort comparison method to alphabetically 

' sort nine words. The sorting method simply compares each possible 

' pair of words; if a pair is out of alphabetical order, they are switched. 
Dim words(l To 9) As String ' the words to sort 

Dim tempstr As String ' buffer used to swap strings 

Dim oc As Integer, ic As Integer ' counter variables 
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Dim compval As Long 








" Get the locale of this thread 
threadlocale = GetThreadLocale () 


' result of comparison 
this thread 








Dim threadlocale As Long ' locale ID of 


(1.e., of this program). 


' Load the nine strings into the array. 





words (1) "can't" 
words(2) = "cant" 
words (3) = "cannot" 
words (4) = "pants" 
words(5) = "co-op" 
words (6) = "coop" 
words(7) = "Denver" 
words (8) = "denver" 
words (9) = "denveR" 


' Sort the strings, 
For oc = 1 To 8 d 


swapping any pairs which are out of 
t string of the pair 


first 


For ic = oc + 1 To 9 
' Compare the two st 


compval = CompareString(threadlocale, 


' second string of the pair 





trings. 





words (ic), Len(words(ic))) 
is greater, 
If compval = CSTR_GREATER_THAN Then 





' If words (oc) 











f order. 








swap them. 














tempstr = words (oc) 
words (oc) = words (ic) 
words (ic) = tempstr 
End If 
Next ic 
Next oc 


' Display the list of sorted words. 


For oc = 1 To 9 
Debug.Print words 
Next oc 





See Also 


SetThreadLocale 





Category 


National Language Support 


(oc) 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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Len (words (oc)), 
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GetTickCount Function 


Declare Function GetTickCount Lib "kernel32.dll1" () As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Unknown. 


Description & Usage 


GetTickCount determines how much time has elapsed since Windows was last started. The time is measured in 
milliseconds, although the actual resolution of the function's output depends on that of the system timer itself. 
Therefore, it may not be perfectly accurate to the millisecond. Because of the limitations of the 32-bit integer data 
type, the reported elapsed time wraps back to zero after about 49.7 days of continuous operation. 


Return Value 


The function returns the number of milliseconds that have passed since Windows was last started. 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


' This code is licensed according to the terms and conditions listed here. 


http://216.26.168.92/vbapi/ref/g/gettickcount.html (1 of 2) [9/1/2002 5:29:19 PM] 


Windows API Guide: GetTickCount Function 








' Determine about how much time it takes for Visual 

' Basic to compute the square root of a large number. The elapsed 
' time for that operation is displayed in seconds. 
Dim starttime As Long ' timer value before the calculation 
Dim endtime As Long ' timer value after the calculation 
Dim result As Double ' receives result of square root operation 

' Find how much time has passed since Windows was started. 





starttime = GetTickCount () 

' Calculate the square root of a large number. 

result = Sgr (54761) 

' Find how much time has now passed since startup. 

endtime = GetTickCount () 

' The difference between starttime and endtime is the time it took 
' to calculate the square root. 





Debug.Print "The calculation took"; (endtime - starttime) / 1000; "seconds." 


Category 


Time 


Back to the Function list. 
Back to the Reference section. 





Last Modified: March 19, 2000 
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GetTimeFormat Function 


Declare Function GetTimeFormat Lib "kernel32.d11" Alias "GetTimeFormatA" (ByVal 
Locale As Long, ByVal dwFlags As Long, lpTime As SYSTEMTIME, ByVal lpFormat As 


Any, ByVal lpTimeStr As String, ByVal cchTime As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetTimeFormat formats a string to display a time according to a locale's settings. The time can be formatted using 
either a predefined format or a custom format specified in the parameter list. The string generated by this function can 
be used to present a more human-readable way to display a time. 





Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
size in bytes of the string placed into the variable passed as /pTimeStr. 


Visual Basic-Specific Issues 


When passing 0 for the /pFormat parameter, the expression CLng(0) must be used. 


Parameters 


Locale 
The identifier of the locale to use to format the string as necessary. If this is 0, the locale of the calling thread is 
used. This can also be one of the following flags specifying a default locale: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
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The user's default locale. 
dwFlags 
A combination of the following flags specifying how to format the time string. If a format string is passed as 
IpFormat, this parameter must be set to 0. 
LOCALE_NOUSEROVERRIDE 
Use the system's default time format for the specified locale, ignoring any changes to those defaults 
which the user may have selected. 
LOCALE_USE_CP_ACP 
Use the system's ANSI code page for string translation instead of the locale's code page. 
TIME_NOMINUTESORSECONDS 
Do not display minutes or seconds. 
TIME_NOSECONDS 
Do not display seconds. 
TIME_NOTIMEMARKER 
Do not display an AM/PM marker. 
TIME_FORCE24HOURFORMAT 
Use a 24-hour time format. 





IpTime 
The time to format as a string. The members of the structure which specify the date are ignored. 

lpFormat 
The format template string used to generate the time string. To use one of the predefined formats, this parameter 
must be 0. In a format template string, the following series of characters stand for the following components of 


the time: 
h 
Hours without a leading zero for single-digit hours, using a 12-hour clock. 
bh 
Hours with a leading zero for single-digit hours, using a 12-hour clock. 
H 
Hours without a leading zero for single-digit hours, using a 24-hour clock. 
HH 
Hours with a leading zero for single-digit hours, using a 24-hour clock. 
m 
Minutes without a leading zero for single-digit minutes. 
mm 
Minutes with a leading zero for single-digit minutes. 
S 
Seconds without a leading zero for single-digit seconds. 
SS 


Seconds with a leading zero for single-digit seconds. 


A one-character AM/PM indicator. 
tt 
A two-character AM/PM indicator. 
Any spaces appearing in the template string appear verbatim in the formatted string. To place any other "fixed" 
characters or text in the format string, you must enclose the literal text in single quotation marks. 
IpTimeStr 
Receives the formatted time string. This must initally be sufficiently long to receive the string. 
cchTime 
The length of the string passed as [pTimeStr. 
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Constant Definitions 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


LOCALE_SYSTEM_ DEFAULT = &H400 
LOCALE_USER_DEFAULT = &H800 
LOCALE _NOUSEROVERRIDE = &H800 
LOCALE_USE_CP_ACP = &H4000000 
TIME _NOMINUTESORSECONDS = &H1 
TIME _NOSECONDS = &H2 

TIME NOTIMEMARKER = &H4 

TIME FORCE24HOURFORMAT = &H8 


Example 


00000 
0 


' This code is licensed according to the terms and conditions listed here. 


' Display today's time first using a "regular" hours-minutes-— 


' AM/PM string and then using a "military hours" format (e.g., 











8:27 AM is 0827 


hours). 

Dim today As SYSTEMTIME ' today's date and time 

Dim timestr As String ' receives the formatted time string 

Dim strlen As Long ' length of the buffer for the formatted time string 


' Get today's date and time in the local time zone. 


GetLoc 


alTime today 








' Make sufficient room in the buffer to receive the time string. 


timest 


r = Space (255) 


' Format today's time as hours-minutes—AM/PM. 


strlen 
' Remo 


= GetTimeFormat (0, TIME NOSE 


m =j 





timest 
' Disp 
Debug. 


ve the empty space from the f 
r = Left (timestr, strlen) 
lay today's time using that f 





CONDS, today, CLng (0), 
ormatted time string. 


ormat. 


Print "It is currently "; timestr 


' Now make sufficient room once again. 


timest 


r = Space (255) 


' Format today's time in the military-esque format. 





"HHmm 'hours'", timestr, 


strlen = GetTimeFormat (0, 0, today, 
' Remove the empty space from the formatted string. 
timestr = Left (timestr, strlen) 


' Display today's time in aforementioned format. 
Print "It is currently "; timestr 


Debug. 


See Also 


GetDateFormat 
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timestr, 


Len (timestr) ) 


Len (timestr) ) 
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Category 


National Language Support 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: January 3, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/gettimeformat.html 
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shop.com | 
GetTimeZonelnformation Function 
Declare Function GetTimeZoneInformation Lib "kernel32.d11" (lpTimeZoneInformation As 














TIME ZONE INFORMATION) As Long 














Platforms: Win 95/98, Win NT 


GetTimeZonelInformation reads the computer's current time zone settings. Since Windows handles all of the system clock 
settings, there usually isn't a need for other programs to use this information. The information is put into the variable passed as 
[pTimeZonelnformation. The function returns 0 if an error occured, or a 1 if successful. 


lpTimeZonelnformation 
Variable which receives the information about the system time zone. 


















































Example: 

' Display the name of the time zone the computer is set to. 

Dim tzi As TIME ZONE INFORMATION ' receives information on the time zone 

Dim retval As Long ' return value 

Dim c As Long ' counter variable needed to display time zone name 

retval = GetTimeZoneInformation (tzi) ' read information on the computer's selected 
time zone 











' Oddly, instead of being stored in a string, the time zone name is stored in a 





























' 32-element array, each element holding the ASCII code of one of the characters. 
' This loop converts the array into a readable string. 
Debug.Print "The computer's time zone is: "; 
For c = 0 To 31 ' the array's range is from 0 to 31 
If tzi.StandardName(c) = 0 Then Exit For ' abort if the terminating null character 
is reached 
Debug.Print Chr(tzi.StandardName (c) ) " convert the ASCII code into a character and 
display it 
Next c 
Debug.Print "" ' end the line being displayed 


Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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GetTopWindow Function 


Declare Function GetTopWindow Lib "user32.d11" (ByVal hwnd As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 

GetTop Window returns a handle to the currently active child window of a window. The active child window is the one 
that has the focus, and it is usually at the top of all the other children in the Z-order. This function works even if the 


parent window is not active. If an error occurs or the window has no children, the function instead returns 0. This 
function is identical to calling GetWindow using the GW_CHILD relationship. 


hwnd 
The handle of the parent window. The function will return its active child window. 


Example: 


' Flash the MDI form window MDIForml's active child once. 
' (In VB, a MDI form has child windows). 












































Dim active As Long ' receives handle to the MDI form's active window 
Dim retval As Long ' return value used for flashing the child window 
active = GetTopWindow (MDIForm1.hWnd) " get the handle of MDIForml's active child 
window 
If active <> 0 Then ' don't try to flash if there is no child window 
' The next three lines flags the window once. 
retval = FlashWindow(active, 1): Sleep 250 
retval = FlashWindow(active, 1): Sleep 250 
retval = FlashWindow(active, 0) 
End If 


See Also: GetWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 


http://216.26.168.92/vbapi/ref/g/gettopwindow.html (1 of 2) [9/1/2002 5:29:53 PM] 


Windows API Guide: GetTopWindow Function 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/gettopwindow.html 





http://216.26.168.92/vbapi/ref/g/gettopwindow.html (2 of 2) [9/1/2002 5:29:53 PM] 


Windows API Guide: GetUserName Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 





| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 


GetUserName Function 














Declare Function GetUserName Lib "advapi32.d1l1" Alias "GetUserNameA" (ByVal lpBuffer 
As String, nSize As Long) As Long 





Platforms: Win 95/98, Win NT 


GetUserName retrieves the name of the user who is logged on to Windows. This user's saved settings are the ones used during 
the current Windows session. The name of the user is placed in the string passed as /pBuffer. The function puts the size of the 
returned string into the variable passed as nSize. The function returns 0 if an error occured, or a non-zero value if successful. 


lpBuffer 
String which receives the name of the user logged on to Windows. The string passed must have sufficient room to 
receive the string the function will give it. 

nSize 
The size of the string passed to the function. The variable passed as this parameter also receives the size of the returned 
string (including the terminating null character). 


Example: 








' Display the name of the user currently logged on. 























Dim username As String ' receives name of the user 

Dim slength As Long ' length of the string 

Dim retval As Long ' return value 

' Create room in the buffer to receive the returned string. 

username = Space (255) ' room for 255 characters 

slength = 255 ' initialize the size of the string 

' Get the user's name and display it. 

retval = GetUserName (username, slength) ' slength is now the length of the returned 
string 

username = Left (username, slength - 1) ' extract the returned info from the buffer 

















' (We subtracted one because we don't want the null character in the trimmed string.) 
Debug.Print "The name of the current user is "; username 











Category: System Information 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 





http://216.26.168.92/vbapi/ref/g/getusername.html (1 of 2) [9/1/2002 5:30:04 PM] 


Windows API Guide: GetUserName Function 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getusername.html 





http://216.26.168.92/vbapi/ref/g/getusername.html (2 of 2) [9/1/2002 5:30:04 PM] 


Windows API Guide: GetVersionEx Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





GetVersionEx Function 


Declare Function GetVersionEx Lib "kernel32.d1l1" Alias "GetVersionExA" 
(lpVersionInformation As OSVERSTONINFO) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GetVersionEx reads information about the version of Windows running as the operating system. This information 
includes the strict version number and platform (3.x with Win32s, Windows 95, Windows NT, Windows 98, etc.). The 
information is put into the variable passed as [pVersionInformation. The function returns 0 if an error occured, or a 1 if 
successful. 


lpVersionInformation 
Receives the version information for the operating system. 


Example: 


' Display the major and minor version numbers of Windows. 
' For example, 4.0 could represent Windows 95. 
Dim os As OSVERSIONINFO ' receives version information 





Dim retval As Long ' return value 





os.dwOSVersionInfoSize = Len (os) " set the size of the structure 
retval = GetVersionEx (os) ' read Windows's version information 
Debug.Print "Windows version number:"; os.dwMajorVersion; "."; os.dwMinorVersion 


Category: System Information 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/g/getversionex.html 
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GetVolumelnformation Function 


Declare Function GetVolumeInformation Lib "kernel32.d11" Alias 
"GetVolumeInformationA" (ByVal lpRootPathName As String, ByVal lpVolumeNameBuffer As 
String, ByVal nVolumeNameSize As Long, lpVolumeSerialNumber As Long, 
lpMaximumComponentLength As Long, lpFileSystemFlags As Long, ByVal 
lpFileSystemNameBuffer As String, ByVal nFileSystemNameSize As Long) As Long 









































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetVolumeInformation retrieves information describing a disk volume and the file system it uses. This information 
includes things such as the volume label and the disk's serial number. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpRootPathName 
The root directory of the disk volume to be described. This directory must include a trailing backslash character. For 
example, to describe the C: drive, this would be "C:\". 
Ip VolumeNameBuffer 
Receives the null-terminated volume label of the volume. This string must be large enough to receive the text. 
nVolumeNameSize 
The length of the string passed as [pVolumeNameBuffer. 
IpVolumeSerialNumber 
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Receives the serial number of the volume. When displayed, this value should be shown in hexadecimal with a dash 
before the last four hex digits. Windows 95/98: If the volume is a netword drive, the serial number will not be 
retrieved. 


IpMaximumComponentLength 


Receives the maximum length of a file name component supported by the file system. A file name component is any 
portion of a file name between backslashes. This value is used primarily to determine if the volume supports long file 


names or if it is limited to the old 8.3 system. 
lpFileSystemFlags 


A combination of the following flags describing other features of the file system used by the volume: 


FS_CASE_IS_PRESERVED 
The file system preserves the case of file names. 
FS_CASE_SENSITIVE 
The file system uses case-sensitive file names. 
FS_UNICODE_STORED_ON_DISK 


The file system supports Unicode in file names as they appear on disk. 


FS_PERSISTENT_ACLS 


The file system preserves and enforces access control lists (ACLs). 


FS_FILE_COMPRESSION 


The file system supports file-based compression, where individual files can be compressed while others are 


not. 


FS_VOL_IS_COMPRESSED 


The entire volume is compressed; for example, DoubleSpace has been used on the disk. 


FILE_NAMED_STREAMS 
The file system supports named streams. 
FILE_SUPPORTS_ENCRYPTION 


The file system supports the Encrypted File System (EFS). 


FILE_SUPPORTS_OBJECT_IDS 


The file system supports object identifiers. 


FILE_SUPPORTS_REPARSE_POINTS 





The file system supports reparse points. 


FILE_SUPPORTS_SPARSE_FILES 

The file system supports sparse files. 
FILE_VOLUME_QUOTAS 
The file system supports disk quotas. 
lpFileSystemNameBuffer 


Receives the null-terminated name of the file system. This string must be long enough to receive the text. 


nFileSystemNameSize 
The length of the string passed as [pF ileSystemNameBuffer. 


Constant Definitions 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


FS_CASE_IS_PRI 





EK SERVED 








FS_CASE_SENSITIVE 


FS_UNICO 
FS_PEI 











= & 





DE_STORED_ON_ 
RSISTENT_ACLS = 


FS_FILE_COMPRESSION = 


FS_VOLUME_1IS_COMP 
FILE _NAMEI 











FILE _SUPPORTS_ENCI 





FILI 





E SUPPORTS_OBJI 





RESS 
D_STREAMS = 


RYPT 





ECT_I 


= &H2 
H1 
DISK = &H4 
&H8 

&H10 
ED = &H8000 
&H40000 
ION = &H20000 
DS &H10000 
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Const FILE _SUPPORTS_REPARSE_ POINTS = &H80 
Const FILE _SUPPORTS_SPARSE_FILES = &H40 
Const FILE VOLUME QUOTAS = &H20 

















Example 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function GetVolumeInformation Lib "kernel32.d1l1" Alias _ 
"GetVolumeInformationA" (ByVal lpRootPathName As String, ByVal 


££ 


lpVolumeNameBuffer _ 

















As String, ByVal nVolumeNameSize As Long, lpVolumeSerialNumber As Long, 
lpMaximumComponentLength As Long, lpFileSystemFlags As Long, ByVal _ 






























































' Display the volume label, serial number, and file system name 

' of the C: drive. Note how the serial number value is manipulated to 
' display it properly. 

Dim volname As String ' receives volume name of C: 

Dim sn As Long ' receives serial number of C: 

Dim snstr As String ' display form of serial number 

Dim maxcomplen As Long ' receives maximum component length 

Dim sysflags As Long ' receives file system flags 

Dim sysname As String ' receives the file system name 

Dim retval As Long ' return value 














' Initialize string buffers. 





volname = Space (256) 

sysname = Space(256) 

' Get information about the C: drive's volume. 

retval = GetVolumeInformation("C:\", volname, Len(volname), sn, maxcomplen, 


sysflags, sysname, Len(sysname) ) 





























' Remove the trailing nulls from the two strings. 
volname = Left (volname, InStr(volname, vbNullChar) - 1) 
sysname = Left (sysname, InStr (sysname, vbNullChar) - 1) 
' Format the serial number properly. 

snstr = Trim (Hex (sn)) 

snstr = String(8 - Len(snstr), "0O") & snstr 

snstr = Left(snstr, 4) & "-" & Right(snstr, 4) 

' Display the volume name, serial number, and file system name. 
Debug.Print "Volume Name: "; volname 

Debug.Print "Serial Number: "; snstr 

Debug.Print "File System: "; sysname 








See Also 


SetVolumeLabel 
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As Long 
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Category 


File System 


Back to the Function list. 
Back to the Reference section. 


Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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GetWindow Function 


Declare Function GetWindow Lib "user32.dll1" (ByVal hwnd As Long, ByVal wCmd As 
Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetWindow returns the handle of a window related to a given window. The relations generally deal with child- 
parent relationships or relationships among children of the same parent window. The exact relation is specified by 
wCmad. If an error occurs or there is no window having the specified relation, the function instead returns 0. 


hwnd 
The handle of the first window in the relation. 
wCmd 
Exactly one of the following flags specifying which relationship the returned window has to the given 
window: 
GW_HWNDFIRST = 0 
The highest window in the Z-order having the same parent as the given window. 
GW_HWNDLAST = 1 
The lowest window in the Z-order having the same parent as the given window. 
GW_HWNDNEXT = 2 
The window below the given window in the Z-order. 
GW_HWNDPREV = 3 
The window above the given window in the Z-order. 
GW_OWNER = 4 
The window that owns the given window (not to be confused with the parent window). 
GW_CHILD =5 
The topmost of the given window's child windows. This has the same effect as using the 
GetTopWindow function. 











Example: 


Flash the application's window that is below Forml in the Z-order 


" once. 











Dim next As Long ' receives handle of next window in the Z-order 

Dim retval As Long ' return value for flashing the window 

next = GetWindow(Forml.hWnd, GW_HWNDNEXT) ' get the handle of the next window 
If next <> 0 Then ' don't try to flags if no such window exists 





iJ 


The next three lines flags the window once. 
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retval FlashWindow(next, 1): Sleep 250 














retval = FlashWindow(next, 1): Sleep 250 








retval = FlashWindow(next, 0) 
End If 





See Also: GetActiveWindow, GetTopWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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GetWindowLong Function 





Declare Function GetWindowLong Lib "user32.dl1" Alias "GetWindowLongA" (ByVal hWnd 
As Long, ByVal nIndex As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetWindowLong retrieves a 32-bit value from the information about a window. This function can also read a 32-bit value 
from the block of extra memory given to the window, if one exists. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 32- 
bit value which was retrieved. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to retrieve a 32-bit value from. 
nIndex 
To get a 32-bit value from the window's extra memory block, this is the zero-based offset of the byte to begin reading 
from. Valid values range from 0 to the size of the extra memory block in bytes minus four. To get a 32-bit value from 
the properties of the window, this is one of the following flags specifying which piece of information to retieve: 
GWL_EXSTYLE 
Retrieve the extended window styles of the window. 
GWL_HINSTANCE 
Retrieve a handle to the owning application's instance. 
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GWL_HWNDPARENT 

Retrieve a handle to the parent window, if any. 
GWL_ID 

Retrieve the identifier of the window. 
GWL_USERDATA 

Retrieve the application-defined 32-bit value associated with the window. 
GWL_STYLE 

Retrieve the window styles of the window. 
GWL_WNDPROC 

Retrieve a pointer to the WindowProc hook function acting as the window's procedure. 
If the window happens to be a dialog box, this could also be one of the following flags: 
DWL_DLGPROC 

Retrieve a handle to the WindowProc hook function acting as the dialog box procedure. 
DWL_MSGRESULT 

Retrieve the return value of the last message processed by the dialog box. 
DWL_USER 

Retrieve the application-defined 32-bit value associated with the dialog box. 





Constant Definitions 


Const GWL_EXSTYLE = -20 
Const GWL_HINSTANCE = -6 
Const GWL_HWNDPARENT = -8 
Const GWL_ID = -12 

Const GWL_STYLE = -16 
Const GWL_USERDATA = -21 
Const GWL_WNDPROC = -4 
Const DWL_DLGPROC = 4 
Const DWL_MSGRESULT 
Const DWL_USER = 8 




















ll 
D 








Example 


When the user clicks button Command1, determine if its parent window has a maximize button or not by checking its 
window style. To use this example, you must first place a command button named Command1 on a form window. 


This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetWindowLong Lib "user32.dl1" Alias "GetWindowLongA" (ByVal 
hWnd As Long, _ 

ByVal nIndex As Long) As Long 
Public Const GWL_STYLE = -16 


Public Const WS_MAXIMIZEBOX = &H10000 























' *** Place the following code inside a form window. *** 





Private Sub Commandl1_Click () 
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Dim styles As Long ' receives window styles of Form! 


' Get the window styles of Forml. 

styles = GetWindowLong(Me.hWnd, GWL_STYLE) 

' Determine if a maximize box exists or not. 

If (styles And WS_MAXIMIZEBOX) = WS_MAXIMIZEBOX Then 














Debug.Print "The form window has a maximize box." 
Else 
Debug.Print "The form window does not have a maximize box." 
End If 
End Sub 
See Also 


GetClassLong, SetWindowLong 





Category 


Window Classes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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GetWindowRect Function 


Declare Function GetWindowRect Lib "user32.d11" (ByVal hwnd As Long, lpRect As RECT) 
As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GetWindowRect reads the size and position of a window. This information is put into the variable passed as /pRect. The 
rectangle receives the coordinates of the upper-left and lower-right corners of the window. If the window is past one of the 
edges of the screen, the values will reflect that (for example, if the left edge of a window is off the screen, the rectangle's . Left 
property will be negative). The function returns 0 if an error occured, or 1 if successful. 


hwnd 
The handle of the window to read the position and width of. 
[pRect 
Variable that receives the coordinates of the upper-left and lower-right corners of the window. 


Example: 


' Display the width and height of window Forml 
' Width and height can be calculated from the coordinates returned in the rectangle. 
Dim r As RECT ' receives window rectangle 








Dim retval As Long ' return value 





retval = GetWindowRect (Forml.hWnd, r) ' set r equal to Forml's rectangle 
Debug.Print "Width ="; r.Right - r.Left 
Debug.Print "Height ="; r.Bottom - r.Top 





See Also: MoveWindow, SetWindowPos 
Category: Windows 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetWindowsDirectory Function 


Declare Function GetWindowsDirectory Lib "kernel32.d11" Alias "GetWindowsDirectoryA" 
(ByVal lpBuffer As String, ByVal nSize As Long) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


GetWindowsDirectory reads the path of the Windows directory. This is where Windows itself is stored, along will all of the 
little applets that come with it. Never assume this is "C:\Windows" because it doesn't necessarily have to be there. The 
directory is put into the string variable passed as lpBuffer. The function returns the length of the returned string if successful, 
or 0 if an error occured. 


lpBuffer 

String variable that receives the path. 
nSize 

The length in characters of lpBuffer. 


Example: 





' Display the location of the Windows directory 
Dim windir As String ' receives path of Windows directory 
Dim slength As Long ' receives length of the string returned 








windir = Space (255) ' initialize buffer to receive the string 

slength = GetWindowsDirectory (windir, 255) ' read the path of the Windows directory 
windir = Left (windir, slength) ' extract the returned string from the buffer 
Debug.Print "The Windows directory is at: "; windir 








See Also: GetSystemDirectory 
Category: System Information 








Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GetWindowRgn Function 





Declare Function GetWindowRgn Lib "user32.d11" (ByVal hWnd As Long, ByVal hRgn As 
Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.51 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


GetWindowRgn obtains a copy of a window's current region. If a non-empty region is applied to a window, it resticts the area 
of the window that is visible, effectively changing its shape as far as the user is concerned. This function copies a window's 
region into a second region passed to the function. 


Return Value 
The function returns one of the following flags specifying the result of the region combination operation: 


ERROR 

An error occured while trying to combine the regions. 
NULLREGION 

The combined region is empty, i.e., null. 
SIMPLEREGION 

The combined region forms a rectangle. 
COMPLEXREGION 

The combined region is not empty but is also not a rectangle. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to get the region of. 
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hRgn 
A handle to a region that receives a copy of the window's region. It doesn't matter what the region passed to the 
function happens to be, because it is overwritten by the function. 


Constant Definitions 





Const ERROR = 0 

Const NULLREGION = 1 
Const SIMPLEREGION = 2 
Const COMPLEXREGION = 3 









































Example 


Use an elliptic region to make window Form1 appear elliptical. Notice how, as this example is written, a portion of the title bar 
is still visible after applying the region. This allows us to move the window without adding any special code providing a 
different way for the user to move the window. Normally, in a real program, you would not want the title bar to be displayed, 
but after all, this is just an example. At least it shows you that the region only changes what part of the window you can see -- 
it doesn't change anything else about the window. 


To run this example, make two windows Form1 and Form2. The latter will be used to illustrate GetWindowRgn. Place the 
following three buttons on Form1: a button labeled "Apply Region" and named cmdApplyRegion, a button labeled "Remove 
Region" and named cmdRemoveRegion, and a button labeled "Show Region" and named cmdShowRegion. Place these 
buttons near the center of Form! to make sure parts of them won't be hidden when the region is applied. 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 



































Public Declare Function GetWindowRgn Lib "user32.dll1" (ByVal hWnd As Long, ByVal hRgn 
As Long) As Long 

Public Declare Function SetWindowRgn Lib "user32.d1l1" (ByVal hWnd As Long, ByVal hRgn 
As Long, _ 








ByVal bRedraw As Boolean) As Long 
Public Declare Function CreateBllipticRgn Lib "gdi32.dl1l1' 











(ByVal nLeftRect As Long, 














ByVal nTopRect _ 
As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long) As Long 

Public Declare Function DeleteObject Lib "gdi32.dl1l1" (ByVal hObject As Long) As Long 

Public Declare Function InvertRgn Lib "gdi32.dl1" (ByVal hdc As Long, ByVal hrgn As 


















































Long) As Long 
' *** Place the following code inside Forml. *** 


' Stores a handle to the special window region, if it exists. 
Private hRgnWindow As Long 








Private Sub Form_Load() 
' Open Form2 when this loads. Form2 is used to display a sort of 
" "shadow" of the region used by Forml, although it really isn't a shadow 
effect. 


Form2.Show 
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Initially disable the "Remove Region" button, sice one hasn't 
yet been applied. 





cmdRemoveRegion.Enabled = False 


End Sub 





Private Sub cmdApplyRegion_Click () 


' 








Create an elliptic region slightly smaller than the current size of 








Forml, and make that the window region. This makes the previously 


4 


rectangular Forml appear to be an ellipse. 





Dim retval As Long ' return value 





First, make the elliptical region, slightly smaller than Forml. 


hRgnWindow = CreateEllipticRgn(5, 5, (Forml.Width / Screen. TwipsPerPixelX) 








(Forml.Height / Screen.TwipsPerPixelY) - 5) 
Apply this region to Forml and show the change immediately. 











retval = SetWindowRgn(Forml.hWnd, hRgnWindow, True) 











To make sure that multiple regions aren't created, disable 
this button and enable the "Remove Region" button. 











cmdApplyRegion.Enabled = False 
cmdRemoveRegion.Enabled = True 


End Sub 











Private Sub cmdRemoveRegion_Click () 


' 





Remove the window region from Forml, returning it to its 
normal rectangular shape. 





Dim retval As Long ' return value 


Set a null window region, which removes the current one entirely. 


retval = SetWindowRgn(Forml.hWnd, 0, True) 


i 














Delete the region object because it is no longer needed. 


retval = DeleteObject (hRgnWindow) 











Since the region no longer exists, enable "Apply Region" and 
disable this button. 


i 








cmdApplyRegion.Enabled = True 
cmdRemoveRegion.Enabled = False 


End Sub 








Private Sub cmdShowRegion_Click() 
Show the region currently applied to Forml by inverting that region on 














' Form2. Note that if no region is applied, nothing appears to happen 
because 

' the actual window region is empty. 

Dim hRgnCopy As Long ' region that receives copy of Forml's region 

Dim retval As Long ' return value 


' 








Create a region. It doesn't matter what, since it will be overwritten 


when GetWindowRgn is called. We just need to have some region. 
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hRgnCopy = CreateFllipticRgn(0, 0, 0, 0) 











' Copy Forml's region to hRgnCopy. The actual value of the handle 
' does not change, but the information it "points" to does. 

retval = GetWindowRgn (Forml.hWnd, hRgnCopy) 

' Invert the colors on Form2 that lie within this region. 

retval = InvertRgn(Form2.hDC, hRgnCopy) 














' Delete the copied region, since we no longer need it. 
retval = DeleteObject (hRgnCopy) 
End Sub 

















See Also 


SetWindowRgn 





Category 


Painting & Drawing 


Back to the Function list. 





Back to the Reference section. 





Last Modified: September 24, 2000 
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Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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GetWindowText Function 


Declare Function GetWindowText Lib "user32.d11" Alias "GetWindowTextA" 
(ByVal hWnd As Long, ByVal lpString As String, ByVal nMaxCount As Long) As 
Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetWindowText retrieves the text of a window. For regular windows, this is the text which appears in the 
title bar. For controls, this is the text in the control. Note that GetWindowText cannot retrieve the text in a 
control owned by another program. To get that text, use the WM_GETTEXT message instead. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns the number of characters copied into the string passed as /pString, not counting the terminating null 
character. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
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A handle to the window to read the title of. 
IpString 
String variable that receives the window's text. This must already have enough room to receive the 
string. 
nMaxCount 
The length in characters of /pString. 


Example 


This code is licensed according to the terms and conditions listed here. 








' Display the text displayed in the title bar of window Forml 











Dim textlen As Long ' receives length of text of the window 
Dim wintext As String ' receives the text of the window 
Dim slength As Long ' receives the length of the returned string 





Find out how many characters are in the window's text. 
' Add 1 to compensate for the terminating null. 

textlen = GetWindowTextLength(Forml.hWnd) + 1 

' Make sufficient room in the buffer. 

wintext = Space (textlen) 

' Retrieve the text of window Forml. 

slength = GetWindowText (Forml.hWnd, wintext, textlen) 

' Remove the empty space from the string, if any. 
































wintext = Left (wintext, slength) 
' Display the result. 
Debug.Print "The title bar of window Forml is: "; wintext 





See Also 


GetWindowTextLength, SetWindowText, WM_GETTEXT 





Category 


Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: February 11, 2000 
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GetWindowTextLength Function 


Declare Function GetWindowTextLength Lib "user32.dll" Alias 
"GetWindowTextLengthA" (ByVal hWnd As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


GetWindowTextLength returns the length in characters of a window's text. You can use this function in 
conjunction with GetWindowText to create a string just long enough to receive the text. However, this 


function does not include the terminating null character in the window's text in the character count. In 
some instances, this function might report a larger text length than actually exists; however, it will never 
report fewer than the actual number of characters. GetWindowTextLength does not work with controls 
owned by other programs. To get the window text length of these controls, use the 
WM_GETTEXTLENGTH message instead. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the 


function returns the number of characters in the window's text, not including the terminating null 
character. 


Visual Basic-Specific Issues 
None. 
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Parameters 


hWnd 
A handle to the window to retrieve the length of the window text of. 


Example 


' Display the text displayed in the title bar of window Forml 





Dim textlen As Long ' receives length of text of the window 
Dim wintext As String ' receives the text of the window 
Dim slength As Long ' receives the length of the returned string 


' Find out how many characters are in the window's text. 
' Add 1 to compensate for the terminating null. 

textlen = GetWindowTextLength (Forml.hWnd) + 1 

' Make sufficient room in the buffer. 

wintext = Space (textlen) 

' Retrieve the text of window Forml. 

slength = GetWindowText (Forml.hWnd, wintext, textlen) 

' Remove the empty space from the string, if any. 
wintext = Left (wintext, slength) 

' Display the result. 

Debug.Print "The title bar of window Forml is: "; wintext 











See Also 


GetWindowText, WM_GETTEXTLENGTH 
Category 
Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: February 12, 2000. 
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GetWindowThreadProcessld Function 





Declare Function GetWindowThreadProcessId Lib "user32.d1l1" (ByVal hwnd As Long, 
lpdwProcessId As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


GetWindowThreadProcesslId finds identifiers for the thread which owns a given window and the process which created it. 
These identifiers can be used to later get information about the program controlling the window. Note that these two values 
are not handles but just numerical identifiers. The process identifier is put into the variable passed as [pdwProcessId, while 
the function returns the thread identifier. 


hwnd 

A handle to the window to find the identifers of the owning thread and creating process. 
IpdwProcesslId 

Receives the identifer for the process which created the window. 


Example: 


' Display the title bar text of all windows controlled by the thread 

' which the window Forml is in. This task is given to the callback function, which 
' will receive each handle individually. Note that if the window has no title bar 
' text, it will not be displayed (for clarity's sake). 








' *** Place this code in a module. This is the callback function. *** 
' This function displays the title bar text of the window identified by hwnd. 
Public Function EnumThreadWndProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 





















































Dim slength As Long, wintext As String ' title bar text length and buffer 
Dim retval As Long ' return value 
Static winnum As Integer ' counter keeps track of how many windows have been 
enumerated 
winnum = winnum + 1 ' one more window enumerated.... 
slength = GetWindowTextLength (hwnd) + 1 ' get length of title bar text 
If slength > 1 ' if return value refers to non-empty string 
buffer = Space(slength) ' make room in the buffer 
retval = GetWindowText (hwnd, buffer, slength) ' get title bar text 
Debug.Print "Window #"; winnum; " : "; ' display number of enumerated window 
Debug.Print Left (buffer, slength - 1) ' display title bar text of enumerated 
window 
End If 
EnumThreadWndProc = 1 ' return value of 1 means continue enumeration 





End Function 
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' *** Place this code wherever you want to enumerate the windows. *** 


Dim threadid As Long, processid As Long ' receive id to thread and process of Forml 
Dim retval As Long ' return value 











' Determine the thread which owns the window Forml. 

threadid = GetWindowThreadProcessId(Forml.hWnd, processid) 

" Use the callback function to list all of the enumerated thrad windows. Note that 
lParam 

' is set to 0 because we don't need to pass any additional information to the 
function. 

retval = EnumThreadWindows(threadid, AddressOf EnumThreadWndProc, 0) 























Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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GlobalAlloc Function 


Declare Function GlobalAlloc Lib "kernel32.dll" (ByVal wFlags As Long, ByVal 
dwBytes As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


GlobalAlloc allocates a series of bytes in the computer's global memory. The memory can be used for any purpose 
necessary. The function's return value, if successful, depends on the flags specified in wFlags. It will either be a pointer 
to the block of allocated memory or a handle to the block of allocated memory. Although they both identify the same 
thing, they will most likely not be equal and cannot be used interchangably! If the function fails, a value of 0 will be 
returned. Note that Windows will not allocate a memory block starting at base address 0. 


wFlags 
One or more of the following flags specifying how to allocate the block of memory: 
GHND = &H40 


Same as combining GMEM_MOVEABLE with GMEM_ZEROINIT. 
GMEM_DDESHARE = &H2000 
Optimize the allocated memory for use in DDE conversations. 
GMEM_DISCARDABLE = &H100 
Allocate discardable memory. (Cannot be combined with GMEM_FIXED.) 
GMEM_FIXED = &H0 
Allocate fixed memory. The function's return value is a pointer to the beginning of the memory block. 
(Cannot be combined with GMEM_DISCARDABLE or GMEM_MOVEABLE.) 
GMEM_MOVEABLE = &H2 
Allocate moveable memory. The memory block's lock count is initialized at 0 (unlocked). The function's 
return value is a handle to the beginning of the memory block. (Cannot be combined with 
GMEM_FIXED.) 
GMEM_NOCOMPACT = &H10 
Do not compact any memory or discard any discardable memory to allocate the requested block. 
GMEM_NODISCARD = &H20 
Do not discard any discardable memory to allocate the requested block. 
GMEM_SHARE = &H2000 
Same as GMEM_DDESHARE. 
GMEM_ZEROINIT = &H40 
Initialize the contents of the memory block to 0. 
GPTR = &H42 
Same as combining GMEM_FIXED with GMEM_ZEROINIT. 








dwBytes 
The number of bytes to allocate; i.e., the size of the memory block to allocate. 


Example: 
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' Use a block of memory as an intermediary step to copy 





" the contents of array s() to array t(). Yes, you could copy them directly, 

' but this demonstrates a few different memory functions. 
Dim s(0 To 255) As Integer, t(0 To 255) As Integer ' arrays to copy from/to 

Dim c As Integer, retval As Long ' counter variable & return value 

Dim hMem As Long, pMem As Long ' handle and pointer to memory block 

' Initialize the source array s()'s data 

For c = 0 To 255 

s(c) =2 * c ' each element equals double its index 
Next c 
' Allocate a moveable block of memory (returns a handle) (Integer type = 2 bytes) 


hMem = GlobalAlloc (GMEM_ MOVEABLE Or GMEM_ZEROINIT, 256 * 2) 

' Lock the memory block, returning a pointer to it 

pMem = GlobalLock (hMem) 

' Copy the entire contents of s() to the memory block 

' Note that pMem is ByVal because we want its contents, not a pointer to it 
CopyMemory ByVal pMem, s(0), 256 * 2 

" Copy the contents of the memory block to t() (we could have just copied s() to 
t()) 

CopyMemory t (0), ByVal pMem, 256 * 2 

' Unlock the memory block, destroying the pointer and freeing resources 

x = GlobalUnlock (hMem) 

' Free the memory block (de-allocate it) 

x = GlobalFree (hMem) 














' Verify that t() = s(), which it should 
For c = 0 To 255 

If s(c) <> t(c) Then Debug.Print "Copy attempt failed." 
End If 


See Also: GlobalFree 
Category: Memory 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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GlobalFree Function 


Declare Function GlobalFree Lib "kernel32.d11" (ByVal hMem As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GlobalFree frees up the resources associated with a memory block, including of course the memory itself. This function 
should be used to deallocate any memory blocks allocated by GlobalAlloc after you are finished using it. The function 


returns 0 if successful, or the value passed as hMem if an error occured. 


hMem 
The handle to the block of memory to free. 


Example: 


' Use a block of memory as an intermediary step to copy 





" the contents of array s() to array t(). Yes, you could copy them directly, 
' but this demonstrates a few different memory functions. 
Dim s(0 To 255) As Integer, t(0 To 255) As Integer ' arrays to copy from/to 
Dim c As Integer, retval As Long ' counter variable & return value 
Dim hMem As Long, pMem As Long ' handle and pointer to memory block 
' Initialize the source array s()'s data 
For c = 0 To 255 
s(c) =2 * c ' each element equals double its index 
Next c 
' Allocate a moveable block of memory (returns a handle) (Integer type = 2 bytes) 


hMem = GlobalAlloc(GMEM_ MOVEABLE Or GMEM_ZEROINIT, 256 * 2) 

' Lock the memory block, returning a pointer to it 

pMem = GlobalLock (hMem) 

' Copy the entire contents of s() to the memory block 

' Note that pMem is ByVal because we want its contents, not a pointer to it 
CopyMemory ByVal pMem, s(0), 256 * 2 











" Copy the contents of the memory block to t() (we could have just copied s() to 


t()) 
CopyMemory t (0), ByVal pMem, 256 * 2 





Unlock the memory block, destroying the pointer and freeing resources 
x = GlobalUnlock (hMem) 

' Free the memory block (de-allocate it) 

x = GlobalFree (hMem) 
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' Verify that t() = s(), which it should 
For c = 0 To 255 

If s(c) <> t(c) Then Debug.Print "Copy attempt failed." 
End If 


See Also: GlobalAlloc 
Category: Memory 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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GlobalLock Function 


Declare Function GlobalLock Lib "kernel32.d11" (ByVal hMem As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GlobalLock locks a moveable block of memory into its current physical position. The block's internal lock count is 
incremented by one; a memory block is considered locked if its lock counter is greater than zero. Memory blocks cannot 
be moved or discarded while locked. The function returns a pointer to the beginning of the memory block if successful, 
or 0 if the function fails. 


hMem 
The handle to the moveable memory block to lock. 


Example: 


' Use a block of memory as an intermediary step to copy 





" the contents of array s() to array t(). Yes, you could copy them directly, 
' but this demonstrates a few different memory functions. 
Dim s(0 To 255) As Integer, t(0 To 255) As Integer ' arrays to copy from/to 
Dim c As Integer, retval As Long ' counter variable & return value 
Dim hMem As Long, pMem As Long ' handle and pointer to memory block 
' Initialize the source array s()'s data 
For c = 0 To 255 
s(c) =2 * c ' each element equals double its index 
Next c 
' Allocate a moveable block of memory (returns a handle) (Integer type = 2 bytes) 


hMem = GlobalAlloc(GMEM_ MOVEABLE Or GMEM_ZEROINIT, 256 * 2) 

' Lock the memory block, returning a pointer to it 

pMem = GlobalLock (hMem) 

' Copy the entire contents of s() to the memory block 

' Note that pMem is ByVal because we want its contents, not a pointer to it 
CopyMemory ByVal pMem, s(0), 256 * 2 





" Copy the contents of the memory block to t() (we could have just copied s() to 


t()) 
CopyMemory t(0), ByVal pMem, 256 * 2 








Unlock the memory block, destroying the pointer and freeing resources 
x = GlobalUnlock (hMem) 

' Free the memory block (de-allocate it) 

x = GlobalFree (hMem) 
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' Verify that t() = s(), which it should 
For © = 0 To 255 

Tf s(c) <> t(c) Then Debug.Print "Copy attempt failed." 
End If 


See Also: GlobalUnlock 
Category: Memory 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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GlobalMemoryStatus Function 





Declare Sub GlobalMemoryStatus Lib "kernel32.d1l1" (lpBuffer As MEMORYSTATUS) 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 

Windows 2000: Supported but Obsolete; use GlobalMemoryStatusEx instead. 
e Windows CE: Unknown. 





Description & Usage 


GlobalMemoryStatus retrieves the current status of the computer's memory. It reports both the total memory available and 
the amount of unused memory. This function only works properly on computers with no more than 4 GB of memory. If the 
computer has more than 4 GB of memory, the values reported by GlobalMemoryStatus are the actual values modulo 4 (for 
example, a computer with 5 GB total memory would be reported as having only 1 GB of memory). For computers with more 
than 4 GB of memory, use the GlobalMemoryStatusEx function instead. 





Return Value 


GlobalMemoryStatusEx does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpBuffer 
Receives the current status of the computer's memory. The dwLength member of the structure does not have to be set 
before calling the function. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Display the amounts of total and available physical memory 
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' on the computer. Also calculate the percentage of used physical memory. 
Dim ms As MEMORYSTATUS 

















' Get the current memory status. 

GlobalMemoryStatus ms 

' Display total and available physical memory, in KB. 
Debug.Print "Total Physical Memory:"; ms.dwTotalPhys \ 1024; "KB" 
Debug.Print "Available Physical Memory:"; ms.dwAvailPhys \ 1024; "KB" 
" Calculate percentage of physical memory in use. 

Debug.Print "Used Physical Memory:"; 100 =- 100 * ms.dwAvailPhys \ ms.dwTotalPhys; 




















wow 
oO 


See Also 


GlobalMemoryStatusEx 





Category 


Memor 


Back to the Function list. 
Back to the Reference section. 
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GlobalMemoryStatusEx Function 


Declare Function GlobalMemoryStatusEx Lib "kernel32.d11" (lpBuffer As 
MEMORYSTATUSEX) As Long 





Platforms 


Windows 95: Not Supported. 
Windows 98: Not Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Description & Usage 


GlobalMemoryStatusEx retrieves the current status of the computer's memory. It reports both the total memory 
available and the amount of unused memory. 


Return Value 


If an error occured, the function returns 0 (call GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpBuffer 
Receives the current status of the computer's memory. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Display the amounts of total and available physical memory 

" on the computer. Use the Currency data type to allow VB to display 
" the 64-bit values reported by GlobalMemoryStatusEx. 

Dim ms As MEMORYSTATUSEX 








Dim temp As Currency ' pseudo-64-bit integer buffer 
Dim retval As Long ' return value 
Dim mult As Long ' conversion multiplier 


" Calculate the multiplier necessary to convert bytes in a Currency variable 
' to kilobytes properly displayed: 

mult = 10000 / 1024 ' move decimal point, bytes to kilobytes 

' Get the current memory status. 

retval = GlobalMemoryStatusEx (ms) 


' Display total physical memory, in KB. 
Debug.Print "Total Physical Memory:"; 
CopyMemory temp, ms.ullTotalPhys, Len(temp) 
Debug.Print temp * mult; "KB" 





' Display available physical memory, in KB. 
Debug.Print "Available Physical Memory:"; 
CopyMemory temp, ms.ullAvailPhys, Len(temp) 
Debug.Print temp * mult; "KB" 





See Also 


GlobalMemoryStatus 





Category 


Memor 


Back to the Function list. 
Back to the Reference section. 





Last Modified: March 19, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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GlobalUnlock Function 


Declare Function GlobalUnlock Lib "kernel32.dl1" (ByVal hMem As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


GlobalUnlock decrements the lock count of a moveable memory block by one. The memory block is locked if its lock 
count is greater than zero; it is considered unlocked if its lock count is zero. A moveable memory block cannot be moved 
or discarded while it is locked. The function returns 1 if, after decrementing the lock count, the memory block is still 
locked. The function returns 0 if, after decrementing the lock count, either the memory block is now unlocked or an error 
occured. 


hMem 
A handle to the moveable memory block to decrement the lock count of. 


Example: 


' Use a block of memory as an intermediary step to copy 








" the contents of array s() to array t(). Yes, you could copy them directly, 
' but this demonstrates a few different memory functions. 
Dim s(0 To 255) As Integer, t(0 To 255) As Integer ' arrays to copy from/to 
Dim c As Integer, retval As Long ' counter variable & return value 
Dim hMem As Long, pMem As Long ' handle and pointer to memory block 
' Initialize the source array s()'s data 
For c = 0 To 255 
s(c) =2 * c ' each element equals double its index 
Next c 
' Allocate a moveable block of memory (returns a handle) (Integer type = 2 bytes) 


hMem = GlobalAlloc(GMEM_ MOVEABLE Or GMEM_ZEROINIT, 256 * 2) 

' Lock the memory block, returning a pointer to it 

pMem = GlobalLock (hMem) 

' Copy the entire contents of s() to the memory block 

' Note that pMem is ByVal because we want its contents, not a pointer to it 
CopyMemory ByVal pMem, s(0), 256 * 2 

















E 


' Copy the contents of the memory block to t() (we could have just copied s() to 


t()) 
CopyMemory t (0), ByVal pMem, 256 * 2 








Unlock the memory block, destroying the pointer and freeing resources 
x = GlobalUnlock (hMem) 
' Free the memory block (de-allocate it) 
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x = GlobalFree (hMem) 





' Verify that t() = s(), which it should 
For c = 0 To 255 

If s(c) <> t(c) Then Debug.Print "Copy attempt failed." 
End If 


See Also: GlobalLock 
Category: Memory 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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htonl Function 
Declare Function htonl Lib "wsock32.d1l1" (ByVal hostlong As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


htonl converts a 32-bit value from host byte order to network byte order. Since Winsock uses network byte order for various 
values, htonl ensures that the proper byte order is being used in Winsock calls, regardless of whether the computer normally 
uses little-endian or big-endian ordering. 


Return Value 


The function returns the value converted to network byte order. 


Visual Basic-Specific Issues 


None. 


Parameters 


hostlong 
A 32-bit value in host order to convert to network byte order. 


Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 
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' This code is licensed according to the tern 





' Declarations and such needed for the exampl 


' (Copy 
Public T 





End Type 
Public D 
Integer, 





Public D 
Public T 








End Type 
Public C 


them to the 
ype WSADATA 
wVersion As Integ 
wHighVersion As 
szDescription As 


(decl 














In 





ns and conditions 


e: 
arations) section of a module.) 
er 

teger 

String * 257 





szSystemStatus As String * 129 


iMaxSockets As Lo 
iMaxUdpDg As Long 
lpVendoriInfo As L 





eclare F 


lpWSAData 
As WSADATA) 
eclare F 


As Lo 








ype HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Int 
h_length As Integ 
h_addr_list As Lo 





onst AF_INET 2 





ng 


ong 


ng 


eger 
er 
ng 


Public 
Public 





Declare Funct 


Declare Functio 


htonl Lib 


"wsock32.dl11" 


unction WSAStartup Lib "wsock32.d11" ( 


unction WSACleanup Lib "wsock32.d11" 


( 





ByVal 





() 





As Long 


ByVal hostlong As Long) 


listed here. 


wVersionRequested As 


As Long 





tion gethostbyaddr Lib 


"wsock32.dl11" 





(addr As Long, 





ByVal length 


As Long, 





ByVal _ 
protocol As Long) 


As Long 


Public 
As Any, 


Public 
As Any) 
Public 
As Any, 





Declare S 


Source _ 
As Any, 


Declare F 


As Long 





Declare F 





ByVal _ 


UNC 





UNC 


ByVal length As Lon 
tion lstrlen Lib 








tion lstrcepy Lib 


lpString2 As Any) 


As Long 


ub CopyMemory Lib "kernel32.d11" Alias 
































"RtlMoveMemory" (Destination 

g) 
"kernel32.d1l1" Alias "lIstrlenA" (ByVal lpString 
"kernel32.dl1l1" Alias "lstrcpyA" (ByVal lpStringl 








Public Type INITCOMMONCONTROLSEX TY 

















PE 








dwSize As Long 






















































































dwICC As Long 
End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INI TCOMMONCONTROLSEX TYPE) As Long 
Public Const ICC_INTERNET_ CLASSES = &H800 
Public Declare Function CreateWindowEx Lib "user32.dl1ll" Alias "CreateWindowExA" 
(ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, 


ByVal hMenu As Lo 








ng, 
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lpParam As Any) 


As Long 


Windows API Guide: htonl Function 
























































Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d1l1" (ByVal hWnd As Long) As Long 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM ISBLANK = &H469 
Public Const IPM GETADDRESS = &H466 


























xxx Place the following code in a form window. 


Private hIPControl As Long 


Privat 


register 


0, 








i 


Private Sub 


When the form is 








upper-left corner of the 

















Dim retval As 


KK* 


' handle to the IP Address control 


initialized, 





form. 


te Sub Form_Initialize() 
Dim comctls As INITCOMMONCONTROLSI 


create an IP Address control in the 











BA TYPE f 








Long 





' Register th 




















With comctls 

.dwSize = Len(comctls) 

-dwICC = ICC_INTERNET_CLASSES 
End With 
retval = InitCommonControlsEx(comctls) 








" Create the IP Address control in the 
WC_IPAD 





hiIPControl 


t257 20, 


Me .hWnd, 
End Sub 














retval 





CreateWindowEx (0, 





0, 


App.hInstance, 


' return value 





End Sub 


Destroy the IP Address control when the 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long 


DestroyWindow (hIPControl1) 














DRESS, 








form close 


identifies the control to 


generic return value 


IP Address control window class. 


wee 
f 


S. 


ByVal CLng(0)) 


corner of the window. 
WS_CHILD Or WS_VISI 

















Look up the primary domain name of the host computer identified by the 


address 





Dim 
im 


im 


im 





im 


im 














im 








in the IP Address control. 
cmdGetDomain_Click() 
ipAddress_h As Long 
ipAddress_n As Long 
sockinfo As WSADATA 
pHostinfo As Long 
hostinfo As HOSTENT 
domainName As String 
retval As Long 


"Ep 
th 
Y an 


= 
= 


E 





' pointer 


E 





1 3n 
' th 
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' generic return val 
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End Sub 


' Veri 
retval 























IP address was entered. 
IPM_ISBLANK, 





fy that an 
= SendMessage(hIPControl, 














ByVal CLng(0), ByVal CLng(0) ) 



















































































































































































If retval <> 0 Then 
Debug.Print "No IP address was entered!" 
Exit Sub 
End If 
' Get the IP address entered by the user and verify that all 
' four fields in the address were entered. 
retval = SendMessage(hIPControl, IPM GETADDRESS, ByVal CLng(0), ipAddress_h) 
If retval < 4 Then 
Debug.Print "An incomplete IP address was entered!" 
Exit Sub 
End If 
' Open up a Winsock v2.2 session. 
retval = WSAStartup(&H202, sockinfo) 
If retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 
End If 
' Convert the IP address into network byte order. 
ipAddress_n = htonl(ipAddress_h) 
' Get information about the host computer. 
pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 
If pHostInfo = 0 Then 
Debug.Print "Could not find a host with the specified IP address." 
Else 
' Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
" Copy the host domain name into a string. 
domainName = Space(lstrien(hostinfo.h_name) ) 
retval = lstrcpy(domainName, hostinfo.h_name) 
Debug.Print "Domain name is: "; domainName 
End If 
' End the Winsock session. 
retval = WSACleanup () 





See Also 


ntohl 


Category 


Winsock 
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Back to the Function list. 





Back to the Reference section. 
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htons Function 
Declare Function htons Lib "wsock32.dll1" (ByVal hostshort As Integer) As Integer 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


htons converts a 16-bit value from host byte order to network byte order. Since Winsock uses network byte order for various 
values, htons ensures that the proper byte order is being used in Winsock calls, regardless of whether the computer normally 
uses little-endian or big-endian ordering. 


Return Value 


The function returns the value converted to network byte order. 


Visual Basic-Specific Issues 


None. 


Parameters 


hostshort 
A 16-bit network address in host order to convert to network byte order. 


Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 
HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 
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Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 


called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 
had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the 
Type WSADATA 
wVersion As Integer 

wHighVersion As Integer 


Public 





End Typ 
Public 
Integer 


ublic 
ublic 
ublic 
ublic 
ong 
ublic 








We to ty to td 





End Typ 
Public 
Integer 
Public 


As Long 








szDescript 
szSystemst 


tio 
tat 








(declarations) section of a module.) 








n As String * 257 
us As String * 129 


iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo 














(= 





As Long 





Declare Function WSAStartup Lib "wsock32.dll1" (ByVal wVersionRequested As 





, lpWSAData _ 
As WSADATA) 








Declare Funct 


Const AF_INET 
Const SOCK_STREAM = 1 
Declare Funct 





Type hostent 








As Long 
ion WSACleanup Lib "wsock32.d11" () As Long 
2 








ion gethostbyname Lib "wsock32.d1l1" (ByVal name As String) As 





h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 





e 





r 





Declare Funct 


Declare Funct 








ion htons Lib "wsock32.dll" (ByVal hostshort As Integer) As 








ion socket Lib "wsock32.dll" (ByVal af As Long, ByVal prototype 


ByVal protocol As Long) As Long 


Public Type sockaddr 


End Typ 
Public 
ByVal n 





argp As 
Public 
Public 


length 





sin_family As Integer 
sin_port As 
sin_addr As Long 

sin_zero As String * 8 


e 





amelen _ 





Integer 





Declare Function connect Lib "wsock32.dll" (ByVal s As Long, name As sockaddr, 


As Long) As Long 








Declare Function ioctlsocket Lib "wsock32.dl1" (ByVal s As Long, ByVal cmd As Long, 





Long) As Long 


Const FIONI 








As Long, 


BIO 


= &H80046671 





Cd 








Declare Function send Lib "wsock32.dll" (ByVal s As Long, buf As Any, ByVal 
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ByVal flags As Long) 


As Long 











































































































Public Declare Function recv Lib "wsock32.d1ll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
Public Const SOCKET_ERROR = -1 
' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val ("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 
End Function 
' *** Place the following code inside the form window. *** 
Private Sub cmdDownload_Click () 
Dim wsockinfo As WSADATA ' info about Winsock 
Dim sock As Long ' the socket descriptor 
Dim pHostinfo As Long ' pointer to info about the host computer 
Dim hostinfo As hostent ' info about the host computer 
Dim plIPAddress As Long ' pointer to host's IP address 
Dim ipAddress As Long ' host's IP address 
Dim sockinfo As sockaddr ' settings for the socket 
Dim buffer As String ' buffer for sending and receiving data 
Dim reply As String ' accumulates server's reply 
Dim retval As Long ' generic return value 
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WSAStartup (MAK 





EWORD 








(2, 2), 





If retval <> 0 Then 


End 





Ii 








F 


End 





Get 
pHostinfo 
If pHostinfo 
Debug.Print 


i 





Lf 








Copy iní 
CopyMemory 
If hostinit 





End 





£ 








' 


Debug.Prin 
Exit Sub 





n 


gethos 


t 








O T 





GoTo Clean 





forma 
hos 











tin 


hen 


up 








O, ByVal p 








fo.h_addr 
Debug.Prin 
GoTo Clean 








Get th 
CopyMemory pIPAddress, 


"Couldn' 


Up 








type <> AF_ 


"Unable to initialize Winsock! 


wsockinfo) 


retval 


We 
r 




















http://216.26.168.92/vbapi/ref/h/htons.html (3 of 5) [9/1/2002 5:32:20 PM] 


Hostinfo, 
INET Then 
t get 


IP address of 


formation about the server to connect to. 
tbyname ("www.vbapi.com") 


"Unable to resolve host!" 





tion about the server into the structure. 





Len (hostinfo) 





www.vbapi.com!" 


server's IP address out of the structure. 
ByVal hostinfo.h_addr_list, 


4 


Windows API Guide: htons Function 





CopyMemory ipAddress, ByVal plIPAddress, 4 


' Create a socket. 

sock = socket (AF_INET, SOCK_STREAM, 0) 

If sock = SOCKET_ERROR Then 

Debug.Print "Unable to create socket!" 
GoTo Cleanup 


























End If 











Make a connection to www.vbapi.com:80 (where the web server listens). 
With sockinfo 

' Use Internet Protocol (IP) 

.-Sin_family = AF_INET 























" Connect to port 80. 
.-Sin_port = htons (80) 
' Connect to this IP address. 


.Sin_addr = ipAddress 
' Padding characters. 
Sin_zero = String(8, vbNullChar) 








End With 








Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, Len(sockinfo) ) 


If retval <> 0 Then 
Debug.Print "Unable to connect!" 
GoTo Cleanup 





End If 














' Send an HTTP/GET request for the / document. 
buffer = "GET / HTTP/1.1" & vbCrLf & _ 

"Host: www.vbapi.com" & vbCrLf & _ 

"User-Agent: HTTP-Test-Program" & vbCrLf & vbCrLf 
retval = send(sock, ByVal buffer, Len(buffer), 0) 





























Debug.Print "Sent request. Waiting for reply..." 








' Make the socket non-blocking, so calls to recv don't halt the program 
waiting for input. 
retval = ioctlsocket (sock, FIONBIO, 1) 








' Read the response from the other system. A more sophisticated program 
' would watch to see if the connection ever times out (i.e., if the 
connection is 
' lost). For brevity, such code is omitted here. 
Do 








buffer = Space (4096) 

retval = recv(sock, ByVal buffer, Len(buffer), 0) 

If retval <> 0 And retval <> SOCKET _ERROR Then 
reply = reply & Left(buffer, retval) 























End If 

" Process background events so the program doesn't appear to freeze. 
DoEvents 

Loop Until retval = 0 
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' Print the response from the server. 
Debug.Print "Document Retrieved:" 
Debug.Print reply 














' Perform the necessary cleanup at the end. 





Cleanup: 
retval = closesocket (sock) 
retval = WSACleanup () 

End Sub 





See Also 


htonl 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/h/htons.html 








http://216.26.168.92/vbapi/ref/h/htons. html (5 of 5) [9/1/2002 5:32:20 PM] 


Windows API Guide: inet_addr Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





inet_addr Function 


Declare Function inet_addr Lib "wsock32.dl1l1" (ByVal cp As String) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


inet_addr converts a string identifying an IP address into an actual IP address in network byte order. The string must be in 
"dotted quad" format (for example, "a.b.c.d"). 


Return Value 


If successful, the function returns the IP address, packed into a single 32-bit integer, in network byte order. If an error 
occured, the function returns & HFFFFFFFF. 


Visual Basic-Specific Issues 


None. 


Parameters 


cp 
The IP address string to convert. This must be in "dotted quad" format. 


Example 


Prompt the user for an IP address by using a regular text box. Take the IP address and determine the domain name, if any, 
associated with that address. 


To use this example, place a command button named cmdGetDomain on a form window. Also place a text box named 
txtIPAddress on the form window. 
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' This 





code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


a 





' (Copy them to the (declarations) section of a module.) 


Public 


Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 








End Type 


Public 





Declare Function WSAStartup Lib "wsock32.d1ll1" (ByVal wVersionRequested As 





Integer, lpWSAData _ 


Public 
Public 








As WSADATA) As Long 

Declare Function WSACleanup Lib "wsock32.dl11" () As Long 
Type HOSTENT 

h_name As Long 

h_aliases As Long 

h_addrtype As Integer 

h_length As Integer 

h_addr_list As Long 





End Type 


Public 
Public 
Public 





Const AF_INET = 2 
Declare Function inet_addr Lib "wsock32.d1l" (ByVal cp As String) As Long 
Declare Function gethostbyaddr Lib "wsock32.dll1" (addr As Long, ByVal length 











As Long, ByVal _ 


Public 
As Any, 


Public 
As Any) 
Public 





As Any, 


protocol As Long) As Long 






























































Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
Source _ 

As Any, ByVal length As Long) 
Declare Function lstrlen Lib "kernel32.d11" Alias "l1strlenA" (ByVal lpString 
As Long 
Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl1 
ByVal _ 


lpString2 As Any) As Long 


' *** Place the following code in a form window. *** 


' Look 





up the primary domain name of the host computer identified by the 


' address in the IP Address control. 
Private Sub cmdGetDomain_Click () 


http://216. 























Dim ipAddress_n As Long ' the IP address, in network byte order 

Dim sockinfo As WSADATA ' information about the Winsock implementation 
Dim pHostinfo As Long ' pointer to information about the host computer 
Dim hostinfo As HOSTENT ' information about the host computer 

Dim domainName As String ' the primary domain name of the host computer 
Dim retval As Long ' generic return value 


' Get the IP address entered by the user. 
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ipAddress_n = inet_addr (txtIPAddress.Text) 

If ipAddress_n = &HFFFFFFFF Then 
Debug.Print "An incorrect IP address was entered!" 
Exit Sub 





End If 


' Open up a Winsock v2.2 session. 
retval = WSAStartup(&H202, sockinfo) 
If retval <> 0 Then 


Debug.Print "ERROR: Attempt to open Winsock failed: 


Exit Sub 
End If 


' Get information about the host computer. 
pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 
If pHostInfo = 0 Then 











Else 
' Copy the data into the structure. 


CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 





" Copy the host domain name into a string. 
domainName = Space(lstrilen(hostinfo.h_name) ) 


retval = lstrcpy(domainName, hostinfo.h_name) 





Debug.Print "Domain name is: "; domainName 
End If 


' End the Winsock session. 
retval = WSACleanup () 
End Sub 


See Also 


inet_ntoa 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 








Last Modified: October 29, 2000 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/i/inet_addr.html 
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error"; retval 





Debug.Print "Could not find a host with the specified IP address." 
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inet_ntoa Function 





Declare Function inet_ntoa Lib "wsock32.dl1l1" (ByVal inaddr As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


inet_ntoa converts an IP address packed in a 32-bit integer into a human-readable string. This string is in the standard 
"a.b.c.d" format. This function returns a pointer to the resulting string. However, the pointer is only guaranteed to be valid 
until the next call to a Winsock function, so your program should make a copy of it immediately. 


Return Value 


If successful, the function returns a pointer to the string that contains the human-readable IP address. If an error occured, the 
function returns zero. 


Visual Basic-Specific Issues 


To copy the returned string into a String variable, use the Istrlen and Istrepy API functions. See the example below for a 
demonstration. 





Parameters 


inaddr 
The IP address to convert to a human-readable string. The IP address is packed into a single 32-bit integer and must be 
in network byte order. 


Example 


Print the IP address associated with a domain name specified by the user. Winsock is briefly used to resolve the domain name 
and format a printable IP address string. The user enters the domain name to resolve in text box txtDomain, and the domain 
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name is resolved when the user clicks button cmdGetIP. 


To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dl11" (ByVal wVersionRequested As 
Integer, lpWSAData _ 
As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 
Public Const AF_INET = 2 
Public Declare Function gethostbyname Lib "wsock32.d1l1" (ByVal name As String) As 
Long 









































Public Declare Function inet_ntoa Lib "wsock32.d1ll1" (ByVal inaddr As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d1l1" Alias "RtlMoveMemory" (Destination 





As Any, Source _ 
As Any, ByVal length As Long) 





















































Public Declare Function lstrlen Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 


As Any, ByVal _ 
lpString2 As Any) As Long 








' Define a relevant API macro. 


Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 


MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 


End Function 


' xxx Place the following code inside the form window. *** 





Private Sub cmdGetIP_Click () 
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Dim sockinfo As WSADATA ' information about Winsock 

Dim hostinfo As HOSTENT ' information about an Internet host 

Dim pHostinfo As Long ' pointer to a HOSTENT structure 

Dim plPAddress As Long ' pointer to an IP address dword 

Dim ipAddress As Long ' an IP address, packed into a dword 

Dim plIPString As Long ' pointer to an IP address formatted as a string 
Dim ipString As String ' holds a human-readable IP address string 

Dim retval As Long ' generic return value 








Open up a Winsock session, using version 2.2. 

retval = WSAStartup (MAKEWORD (2, 2), sockinfo) 

If retval <> O Then 

Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 








Exit Sub 
End If 


Get information about the domain specified in txtDomain. 
pHostinfo = gethostbyname (txtDomain. Text) 

If pHostinfo = 0 Then 

Debug.Print "Unable to resolve domain name." 








Else 

' Copy the data into a HOSTENT structure. 

CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "A non-IP address was returned." 











Else 

' Copy the pointer to the first (and probably only) IP 
address in the structure. 

CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 

' Copy the actual IP address. 

CopyMemory ipAddress, ByVal plIPAddress, 4 

" Convert the IP address into a human-readable string. 

piPString = inet_ntoa(ipAddress) 

' Copy the result into a string variable. 

ipString = Space(lstrilen(pIPString) ) 











retval = lstrcpy(ipString, pIPString) 
' Print the result: a human-readable IP address. 
Debug.Print ipString 








End If 
End If 


Close the Winsock session. 
retval = WSACleanup () 
End Sub 


See Also 


inet_addr 
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Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 


Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/i/inet_ntoa.html 
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InflateRect Function 





Declare Function InflateRect Lib "user32.d1l" (lpRect As RECT, ByVal x As Long, 
ByVal y As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


InflateRect increases or decreases the size of a rectangle. The values to inflate the rectangle by are added to both sides of it, 
so in reality the width and/or height of the rectangle increases by double what you pass to the function. For example, if you 
pass 20 as x, the left and right sides will both be extended by 20, so the total width will be 40 more. Positive values increase 
the size, while negative values decrease it. The function returns 0 if an error occured, or 1 if successful. 


[pRect 
The rectangle to change the size of. 
x 
The value to expand the left and right sides by. Positive values increase the width; negative values decrease it. 


The value to expand the top and bottom by. Positive values increase the height; negative values decrease it. 
Example: 
' Expand the width of window Forml by 100 and shrink its 


' height by 50 using its rectangle. 
Dim winrect As RECT ' receives the rectangle of the window 








Dim retval As Long ' return value 





retval GetWindowRect (Forml.hWnd, winrect) ' get Forml's rectangle 








retval InflateRect (winrect, 50, -—25) " these values added to each side to inflate 
it 

' Now change the window on screen to match its new rectangle 

retval = SetWindowPos(Forml.hWnd, 0, winrect.Left, winrect.Top, winrect.Right, 








winrect.Bottom, 0) 


See Also: OffsetRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/i/inflaterect.html 
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InitCommonControlsEx Function 











Declare Function InitCommonControlsEx Lib "comct132.d11" (lpInitCtrls As 
INITCOMMONCONTROLSEX TYPE) As Long 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


InitCommonControlsEx registers the window classes used to create various common controls. This function must be called 
before using CreateWindowEx to create a common control. 





Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pInitCtrls 
Specifies which common control classes to register. 


Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 

wVersion As Integer 

wHighVersion As Integer 

szDescription As String * 257 

szSystemStatus As String * 129 

iMaxSockets As Long 

iMaxUdpDg As Long 

lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.d1ll" ( 
































ByVal 





Integer, lpWSAData 
As WSADATA) 
Public Declare Function WSACleanup Lib "wsock32.dl11" 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 
Public Const AF_INET = 2 


As Long 








() 












































Public Declare Function htonl Lib "wsock32.d11" ( 
Public Declare Function gethostbyaddr Lib "wsock32.dl11" 
As Long, ByVal _ 

protocol As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias 
As Any, Source _ 

As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d1ll1" Alias 
As Any) As Long 
Public Declare Function Ilstrcpy Lib "kernel32.d1l1" Alias 


As Any, 











ByVal _ 


lpString2 As Any) 
Public Type INITCOMMONCONTROLS! 





As Long 

















EX TYPE 








dwSize As Long 
dwICC As Long 
































As Long 


ByVal hostlong As Long) 


(addr As Long, ByVal length 











End Type 

Public Declare Function InitCommonControlsEx Lib "comct132.dl1" 
INITCOMMONCONTROLSEX TYPE) As Long 

Public Const ICC_INTERNET_ CLASSES = &H800 

Public Declare Function CreateWindowEx Lib "user32.dll1" Alias "Crea 




















~ 


ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, 
ByVal x _ 

As Long, ByVal y As Long, 
hWndParent As Long, 
ByVal hMenu As Long, 

















Long, 








ByVal nWidth As Long, 








ByVal hInstance As Long, 
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ByVal lpWindowName As String, 


lpParam As Any) 





wVersionRequested As 


As Long 














"RtlMoveMemory" (Destination 
"IstrlenA" (ByVal lpString 
"IstrcpyA" (ByVal lpStringl 





(lpInitCtrls As _ 





teWindowExA" 





ByVal nHeight As Long, 


As Long 


ByVal dwStyle As 





ByVal 
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Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d1ll1" (ByVal 
Public Declare Function SendMessage Lib "user32.dl1" Alias "Se 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM ISBLANK = &H469 
Public Const IPM GETADDRESS = &H466 


Private hIPControl As Long 


When the form 


























xxx Place the following code in a form window. 


is 





initialized, 





ft corner of the 





form. 





upper-let 


Private Sub Form_Initialize() 





register 


ub 











End Sub 




















KK* 








Dim comctls As INITCOMMONCONTROLSEX 





TYPE 


























ET_CLASSES 





Dim retval As Long 
' Register th 
With comctls 
.dwSize = Len(comctls) 
-dwICC = ICC_INTERN 
End With 
retval = InitCommonControlsEx(comctls) 





address 
Private Sub 








IP Address control window class. 


handle to the IP Address control 


hWnd As Long) 
( 


As Long 
ByVal hWnd 





ndMessageA" 


create an IP Address control in the 


identifies the control to 


generic return value 


Create the IP Address control in the corner of the window. 






































































































































IPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0O, 
O, _ 
Me.hWnd, 0, App.hInstance, ByVal CLng(0) ) 
Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 
retval = DestroyWindow (hIPControl) 
Look up the primary domain name of the host computer identified by the 
in the IP Address control. 
cmdGetDomain_Click () 
im ipAddress_h As Long ' the IP address, in host byte order 
im ipAddress_n As Long ' the IP address, in network byte order 
im sockinfo As WSADATA ' information about the Winsock implementation 
im pHostinfo As Long ' pointer to information about the host computer 
im hostinfo As HOSTENT ' information about the host computer 
im domainName As String ' the primary domain name of the host computer 
im retval As Long ' generic return value 
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End Sub 





" Verify that an IP address was entered. 

retval = SendMessage(hIPControl, IPM ISBLANK, ByVal CLng(0), ByVal CLng(0)) 
If retval <> 0 Then 

Debug.Print "No IP address was entered!" 

Exit Sub 























End If 











' Get the IP address entered by the user and verify that all 

' four fields in the address were entered. 

retval = SendMessage(hIPControl, IPM GETADDRESS, ByVal CLng(0), ipAddress_h) 
If retval < 4 Then 

Debug.Print "An incomplete IP address was entered!" 

Exit Sub 









































End If 





' Open up a Winsock v2.2 session. 
retval = WSAStartup(&H202, sockinfo) 
If retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 








End If 











" Convert the IP address into network byte order. 
ipAddress_n = htonl(ipAddress_h) 
' Get information about the host computer. 
pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 
If pHostInfo = 0 Then 
Debug.Print "Could not find a host with the specified IP address." 














Else 
' Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len (hostinfo) 











' Copy the host domain name into a string. 
domainName = Space(lstrien(hostinfo.h_name) ) 








retval = lstrcpy(domainName, hostinfo.h_name) 








Debug.Print "Domain name is: "; domainName 








' End the Winsock session. 
retval = WSACleanup () 








Category 


Common Controls 





Back to the Function list. 
Back to the Reference section. 
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Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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shop.com | 
InsertMenultem Function 
Declare Function InsertMenuItem Lib "user32.dll" Alias "InsertMenuItemA" (ByVal hMenu 























As Long, ByVal ulItem As Long, ByVal fByPosition As Long, lpmii As MENUITEMINFO) As 
Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


InsertMenultem adds a menu item to a menu that already exists. The new item can be inserted at any point in the menu. If the 
menu is a regular menu, then the window it belongs to will receive a WM_COMMAND message whenever the menu item is 
selected. If the menu is a window's system menu, then the window receives the WM_SYSCOMMAND message instead. 








Also, when adding an item to a window's system menu, be sure that the new item's unique menu item identifier is less than 
&HF000. All identifiers greater than that are reserved for items that the system places there (such as Restore, Minimize, etc.). 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


When using InsertMenultem to add something to a menu, keep in mind that there is no way for Visual Basic to create an 
event handler to run when the item is selected. Instead, it is necessary to create a WindowProc window procedure to manually 


process the WM_COMMAND or WM_SYSCOMMAND messages that the menu item may send. See the example below for a 
demonstration of how to accomplish this. 


Parameters 


hMenu 
A handle to the menu to add a new item to. 
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ultem 
Identifies the existing menu item that appears immediately before the point where you want to add the new item. This 
could be either a position or a menu item identifier, depending on fByPosition. 

JByPosition 
If this is a non-zero value, ultem indicates the existing item by using its zero-based position. (For example, the first item 
in the menu has a position of 0.) If this is zero, then ultem is the unique menu item identifier of the existing item. 

Ipmii 
Describes the menu item to be added. 


Example 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
' There's quite a few declarations for this example, but it's worth it! 















































Public Declare Function GetSystemMenu Lib "user32.d1l1" (ByVal hWnd As Long, ByVal 
bRevert _ 

As Long) As Long 
Public Declare Function GetMenulItemCount Lib "user32.dl1" (ByVal hMenu As Long) As 
Long 
Public Type MENUITEMINFO 


cbhSize As Long 

fMask As Long 

fType As Long 

fState As Long 

wID As Long 

hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwiItemData As Long 
dwTypeData As String 
cch As Long 




















End Type 

Public Con 
Public Con 
Public Con 
Public Con 
P 
P 
P 
P 
( 





IIM_STATE = &H1 
IIM_ID = &H2 

IIM TYPE = &H10 
FT_SEPARATOR = &H800 
ublic Con FT_STRING = &HO 
ublic Con FS ENABLED = &HO 
ublic Const MFS_ CHECKED = &H8 
ublic Declare Function InsertMenuItem Lib "user32.dll" Alias "InsertMenuItemA" 
ByVal 


























is = Ss Ss SS 

















ee 
T 



























































hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 
ublic Declare Function SetMenulItemInfo Lib "user32.d11" Alias "SetMenulItemInfoA" 
ByVal 























tg 














~ 




















hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 
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Public Declare Function SetWindowPos Lib "user32.dll1" (ByVal hWnd As Long, ByVal _ 
hWndInsertAfter As Long, ByVal x As Long, ByVal y As Long, ByVal cx As Long, 

ByVal _ 
cy As Long, ByVal wFlags As Long) As Long 

Public Const HWND_TOPMOST = -1 

Public Const HWND_NOTOPMOST = -2 

Public Const SWP_NOMOVE = &H2 

Public Const SWP_NOSIZE = &H1 




















Public Declare Function SetWindowLong Lib "user32.dll" Alias "SetWindowLongA" (ByVal 
hWnd _ 














As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 

















Public Const GWL_WNDPROC = -4 
Public Declare Function CallWindowProc Lib "user32.d11" Alias "CallWindowProcA" 
(ByVal _ 











lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 

Public Const WM SYSCOMMAND = &H112 

Public Const WM INITMENU = &H116 




















' Add an option to make window Forml "Always On Top" to the bottom of its system 

' menu. A check mark appears next to this option when active. The menu item acts as 
a toggle. 

' Note how subclassing the window is necessary to process the two messages needed 

" to give the added system menu item its full functionality. 














' *** Place the following code in a module. *** 





Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public ontop As Boolean ' identifies if Forml is always on top or not 

















' The following function acts as Forml's window procedure to process messages. 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 












































As Long, ByVal lParam As Long) As Long 
Dim hSysMenu As Long ' handle to Forml's system menu 
Dim mii As MENUITEMINFO ' menu item information for Always On Top 
Dim retval As Long ' return value 


Select Case uMsg 
Case WM INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 
With mii 
' Size of the structure. 
.cbSize = Len (mii) 
' Only use what needs to be changed. 
.fMask = MIIM_STATE 
' If Forml is now always on top, check the item. 










































































.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenultemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 
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Case WM SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 














top 
' setting of Forml to match. 
If wParam = 1 Then 
" Reverse the setting and make it the current one. 
ontop = Not ontop 


retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 


























HWND_NOTOPMOST), 





0; O, O, O, SWP_NOMOVE Or SWP_NOSTIZI 








Cd 
~ 




















WindowProc = 0 
Else 
' Some other item was selected. Let the previous window 
procedure 
' process it. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, 
lParam) 
End If 
Case Else 
' If this is some other message, let the previous procedure handle 
Tt. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 








End Select 
End Function 





xxx Place the following code inside Forml. *** 


' When Forml loads, add Always On Top to the system menu and set up the 























new window procedure. 
Private Sub Form_Load() 
Dim hSysMenu As Long ' handle to the system menu 
Dim count As Long " the number of items initially on the menu 
Dim mii As MENUITEMINFO ' describes a menu item to add 
Dim retval As Long ' return value 


Get a handle to the system menu. 
hSysMenu = GetSystemMenu(Forml.hWnd, 0) 





See how many items are currently in it. 
count = GetMenultemCount (hSysMenu) 











Add a separator bar and then Always On Top to the system menu. 
With mii 
' The size of the structure. 

.cbSize = Len (mii) 

' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 

.£Type = MFT_SEPARATOR 

' It has an ID of O. 

wID = 0 
































End With 
' Add the separator to the end of the system menu. 
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retval = InsertMenulItem(hSysMenu, count, 1, mii) 


' Likewise, add the Always On Top command. 
With mii 
.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' This is a regular text item. 
.fType = MFT_STRING 
The option is enabled. 
-fState = MFS_ ENABLED 
' It has an ID of 1 (this identifies it in the window procedure). 

































































.wID = 1 
' The text to place in the menu item. 
-dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenuItem(hSysMenu, count + 1, 1, mii) 
' Set the custom window procedure to process Forml's messages. 


ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 


End Sub 














E 


' Before unloading, restore the default system menu and remove the 
' custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 




















' Replace the previous window procedure to prevent crashing. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
' Remove the modifications made to the system menu. 
retval = GetSystemMenu(Forml.hWnd, 1) 
End Sub 





























Category 


Menus 


Back to the Function list. 
Back to the Reference section. 


Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/i/insertmenuitem.html 
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IntersectRect Function 


Declare Function IntersectRect Lib "user32.d1l1" (lpDestRect As RECT, lpSrclRect As 
RECT, lpSrc2Rect As RECT) As Long 























Platforms: Win 32s, Win 95/98, Win NT 


IntersectRect creates a rectangle based on the intersecting part of two other rectangles. The rectangular region where the two 
source rectangles overlap is the intersection rectangle. If one or both of the source rectangles are empty or there is no 
intersection, the function returns 0 and the /pDestRect rectangle is set to (0,0)-(0,0). If the source rectangles do overlap, the 
intersection is put into /pDestRect and the function returns 1. 


[pDestRect 

The rectangle to be set as the intersection of the two source rectangles. 
lpSrcl Rect 

The first source rectangle. 
lpSrc2Rect 

The second source rectangle. 


Example: 





' Determine if windows Forml and Form2 are overlapping on the 
















































































' screen. If they don't the intersection rectangle will be empty. 

Dim intrect As RECT ' receives the intersection rectangle 

Dim windowl As RECT, window2 As RECT ' receive rectangles of Forml and Form2 

Dim result As Long ' will be set to 0 if no intersection, 1 if there is intersection 
Dim retval As Long ' return value for other functions 

retval = GetWindowRect (Forml.hWnd, window1) ' get Forml's rectangle 

retval = GetWindowRect (Form2.hWnd, window2) ' get Form2's rectangle 

result = IntersectRect (intrect, windowl, window2) ' determine the intersection 
rectangle 

If result = 0 ' in this case, intrect will also be empty 











Debug.Print "Windows Forml and Form2 are not overlapping on the screen." 
Else 
Debug.Print "Windows Forml and Form2 are overlapping on the screen." 
End If 























See Also: SubtractRect, UnionRect 
Category: Rectangles 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





http://216.26.168.92/vbapi/ref/i/intersectrect.html (1 of 2) [9/1/2002 5:33:00 PM] 


Windows API Guide: IntersectRect Function 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/i/intersectrect.html 
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InvertRect Function 


Declare Function InvertRect Lib "user32.dl1" (ByVal hdc As Long, ByVal 
lpRect As RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


InvertRect inverts the image inside a rectangular area on a device. The inverted colors are calculated by taking 
the binary NOT of each pixel's RGB color value inside the rectangle. The function returns a non-zero value if 
successful, or 0 if an error occured. 


hdc 

A device context to the device to invert the colors in a given rectangle on. 
lpRect 

The rectangle to invert. 


Example: 

' Invert the colors in the rectangle (20,30)-(150,100) on window Forml. 

Dim r As RECT ' rectangle to invert 

Dim retval As Long ' return value 

retval = SetRect(r, 20, 30, 150, 100) " set r to be (20,30)-(150,100) 
retval = InvertRect (Forml.hDC, r) ' invert the pixels within the rectangle 


See Also: InvertRgn 
Category: Filled Shapes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/i/invertrect.html 
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InvertRgn Function 


Declare Function InvertRgn Lib "gdi32.dll1" (ByVal hdc As Long, ByVal 
hRgn As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 
InvertRgn inverts the colors of all the pixels inside a region on a given device. The inverse of the pixels 


is calculated by doing a binary NOT operation on the RGB color value of each pixel. The function 
returns 0 if an error occured, or a non-zero value if successful. 


hdc 
A device context to the device to invert the pixels within a region of. 
hRgn 
A handle to the region on the device to invert. 
Example: 
' Invert the pixels within an elliptical region on window Forml. The 
' elliptical region has a bounding rectangle of (20,30)-(150,110). 
Dim hrgn As Long ' handle to the region to invert 
Dim retval As Long ' return value 





' Create the elliptical region to invert and get a handle to it. 
hrgn = CreateBllipticRgn (20,30,150,110) 

' Invert that region in window Forml. 

retval = InvertRgn(Forml.hDC, hrgn) 

" Delete the region to free up resources. 

retval = DeleteObject (hrgn) 














See Also: InvertRect 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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loctisocket Function 








Declare Function ioctlsocket Lib "wsock32.dl1" (ByVal s As Long, ByVal cmd As Long, 
argp As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


ioctlsocket manipulates the i/o mode of a socket. It gets or sets parameters that control how the socket performs input and 
output. Naturally, the socket must have been created by a previous call to socket. 


Return Value 


If successful, the function returns zero. If an error occured, the function returns SOCKET_ERROR (use WSAGetLastError to 
get the error code). 


Visual Basic-Specific Issues 


When setting cmd to FIONBIO, do not use the ByVal keyword in front of the parameter passed as argp. 


Parameters 


The descriptor of the socket to manipulate. 
cmd 

One of the following flags specifying the action to take: 

FIONBIO 
Set the blocking mode of the socket. If argp is zero, the socket is set to block (halt the program if no data is yet 
available to read from the socket), which is the default value. If this is a non-zero value, the socket is set to 
nonblocking mode, where functions reading the socket return immediately instead of waiting for input to arrive. 

FIONREAD 
Determine the amount of data sitting in the socket's input buffer. The variable passed as argp receives the 
number of bytes sitting in the buffer waiting to be read. (For datagram-based sockets, this value is the size of the 
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first datagram in the buffer.) 

SIOCATMARK 
Determine if there is any out-of-band data waiting to be read from the socket. If so, the variable passed as argp 
receives zero, and the next attempt to read from the socket will read from the out-of-band data. If there is no 
unread out-of-band data, argp receives a non-zero value. 


argp 
Usage depends on the flag used for cmd. 


Constant Definitions 





Const FIONBIO = &H8004667E 
Const FIONREAD = &H4004667F 
Const SIOCATMARK = &H40047307 
Const SOCKET ERROR = -1 









































Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 





HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 


Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 
called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 


had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dll" (ByVal wVersionRequested As 



































Integer, lpWSAData _ 
As WSADATA) As Long 















































Public Declare Function WSACleanup Lib "wsock32.d1l1" () As Long 

Public Const AF_INET = 2 

Public Const SOCK_STREAM = 1 

Public Declare Function gethostbyname Lib "wsock32.dll" (ByVal name As String) As 
Long 

Public Type hostent 
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End Typ 
Public 


Integer 
Public 
As Long 


h_name As 
h_aliases 
h_addrtyp 
h_length 
h_addr_1li 
e 





Declare Fu 





Declare Fu 


r 


ByVal pro 





Long 

As Long 

e As Integer 
As Integer 
st As Long 








nction htons Lib "wsock32.dll 








nction socket Lib 


"wsock32.d11" 


(ByVal hostshort As Integer) As 








(ByVal af As Long, ByVal prototype 





tocol As Long) As Long 


Public Type sockaddr 











sin_famil 





sin port 
sin_addr 
sin_zero 
End Type 
Public Declare Fu 
ByVal namelen _ 
As Long) 


y As Integer 
As Integer 

As Long 

As String * 8 


nction connect Lib 


As Long 


















































"wsock32.dl11" 





(ByVal s As Long, name As sockaddr, 








































































































Declare Function ioctlsocket Lib "wsock32.dl1" (ByVal s As Long, ByVal cmd As Long, 
argp As Long) As Long 
Public Const FIONBIO = &H8004667E 
Public Declare Function send Lib "wsock32.dl1" (ByVal s As Long, buf As Any, ByVal 
length As Long, 
ByVal flags As Long) As Long 
Public Declare Function recv Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
Public Const SOCKET_ERROR = -1 
' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 
End Function 
' ***x Place the following code inside the form window. *** 
Private Sub cmdDownload_Click () 
Dim wsockinfo As WSADATA ' info about Winsock 
Dim sock As Long " the socket descriptor 
Dim pHostinfo As Long ' pointer to info about the host computer 
Dim hostinfo As hostent ' info about the host computer 
Dim plPAddress As Long ' pointer to host's IP address 
Dim ipAddress As Long ' host's IP address 
Dim sockinfo As sockaddr ' settings for the socket 
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Dim buffer As String ' buffer for sending and receiving data 
Dim reply As String " accumulates server's reply 
Dim retval As Long ' generic return value 








' Begin a Winsock session. 

retval = WSAStartup (MAKEWORD (2, 2), wsockinfo) 

If retval <> 0 Then 

Debug.Print "Unable to initialize Winsock! --"; retval 
Exit Sub 














End If 











' 


Get information about the server to connect to. 











pHostinfo = gethostbyname ("www.vbapi.com") 

If pHostinfo = 0 Then 
Debug.Print "Unable to resolve host!" 
GoTo Cleanup 





End If 
' Copy information about the server into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 

If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "Couldn't get IP address of www.vbapi.com!" 
GoTo Cleanup 



























































End If 

' Get the server's IP address out of the structure. 
CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 
CopyMemory ipAddress, ByVal plIPAddress, 4 

















' Create a socket. 

sock = socket (AF_INET, SOCK_STREAM, 0) 

If sock = SOCKET _ERROR Then 

Debug.Print "Unable to create socket!" 
GoTo Cleanup 


























End If 





Make a connection to www.vbapi.com:80 (where the web server listens). 
With sockinfo 

" Use Internet Protocol (IP) 
.-Sin_family = AF_INET 




















" Connect to port 80. 
-Sin_port = htons (80) 
" Connect to this IP address. 








.-Sin_addr = ipAddress 
' Padding characters. 
-Sin_zero = String(8, vbNullChar) 
End With 
Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, Len(sockinfo) ) 
If retval <> 0 Then 
Debug.Print "Unable to connect!" 
GoTo Cleanup 
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' Send an HTTP/GET request for the / document. 
buffer = "GET / HTTP/1.1" & vbCrLf & _ 

"Host: www.vbapi.com" & vbCrLf & _ 

"User-Agent: HTTP-Test-Program" & vbCrLf & vbCrLf 
retval = send(sock, ByVal buffer, Len(buffer), 0) 
Debug.Print "Sent request. Waiting for reply..." 


























' Make the socket non-blocking, so calls to recv don't halt the program 
waiting for input. 
retval = ioctlsocket (sock, FIONBIO, 1) 








' 


Read the response from the other system. A more sophisticated program 
would watch to see if the connection ever times out (i.e., if the 
connection is 








' lost). For brevity, such code is omitted here. 
Do 
buffer = Space (4096) 
retval = recv (sock, ByVal buffer, Len (buffer), 0) 














If retval <> 0 And retval <> SOCKET_ERROR Then 
reply = reply & Left (buffer, retval) 














End If 

' Process background events so the program doesn't appear to freeze. 
DoEvents 

Loop Until retval = 0 

















' Print the response from the server. 
Debug.Print "Document Retrieved:" 
Debug.Print reply 














Perform the necessary cleanup at the end. 





Cleanup: 
retval = closesocket (sock) 
retval = WSACleanup () 

End Sub 





Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 
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IsChild Function 


Declare Function IsChild Lib "user32.d1ll" (ByVal hWndParent As Long, ByVal hWnd 
As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


IsChild determines if a parent-child relationship exists between two windows. The possible child window must be a 
direct descendant of the possible parent window. For example, if the possible child window is a child of a child of the 
possible parent window, the parent-child relationship does not exist. 


Return Value 


If a parent-child relationship does not exist between the two windows, the function returns 0. If the relationship does 
exist, the function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWndParent 

A handle to the candidate parent window. 
hWnd 

A handle to the candidate child window. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Demonstrate a parent-child relationship and a non-parent-child 

' relationship. Commandl, a command button on window Forml, is a child 
' of Forml. However, fellow window Form2 is not a child. 

Dim result As Long ' result of the function 


' Verify that Commandl is a child of Forml. 


result = IsChild(Forml.hWnd, Command1.hWnd) ' see if Forml is Commandl's parent 
If result = 0 Then 
Debug.Print "Forml is not Commandl's parent window." ' won't happen 
Else 
Debug.Print "Forml is Commandl's parent window." ' will happen 
End If 


' Verify that Form2 is not a child of Forml. 


result = IsChild(Forml.hWnd, Form2.hWnd) ' see if Forml is Form2's parent 
If result = 0 Then 

Debug.Print "Forml is not Form2's parent window." ' will happen 
Else 

Debug.Print "Forml is Form2's parent window." ' won't happen 


See Also 


IsWindow, SetParent 


Category 


Windows 


Back to the index. 
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Isiconic Function 











Declare Function IsIconic Lib "user32.d1ll1" (ByVal hwnd As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


IsIconic finds if a given window is minimized or not. The function returns 0 if the window is not minimized (it 
could be either restored or maximized); it returns a non-zero value if the window is minimized. 


hwnd 
A handle to the window to find whether it is minimized or not. 


Example: 


' Determine if the window Forml is maximized, minimized, or restored. 























Dim minflag As Long, maxflag As Long ' receive minimized or maximized status 
minflag = IsIconic(Forml1.hWnd) ' is Forml minimized? 
maxflag = IsZoomed (Forml.hWnd) ' is Forml maximized? 





If minflag <> 0 Then 
Debug.Print "Forml is minimized." 
Elseif maxflag <> 0 Then 
Debug.Print "Forml is maximized." 
Else 
Debug.Print "Forml is restored." 
End If 

















See Also: IsZoomed, ShowWindow 
Category: Windows 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi @vbapi.com Send Encrypted E-Mail 





http://216.26.168.92/vbapi/ref/i/isiconic.html (1 of 2) [9/1/2002 5:33:37 PM] 


Windows API Guide: IsIconic Function 


This page is at http://www.vbapi.com/ref/i/isiconic.html 


http://216.26.168.92/vbapi/ref/i/isiconic.html (2 of 2) [9/1/2002 5:33:37 PM] 


http://216.26.168.92/vbapi/ref/i/isrectempty html 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





IsRectEmpty Function 





Declare Function IsRectEmpty Lib "user32.dll1" (lpRect As RECT) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


IsRectEmpty checks to see if a rectangle is empty. A rectangle is considered empty if its right edge is not to the right of its 
left edge and/or its bottom edge is not below its top edge. For example, a rectangle (50,50)-(25,100) is empty because the 
right edge is to the left of the left edge. The function returns 1 if the rectangle is empty and 0 if it is not. 


IpRect 
The rectangle to check. 


Example: 





' Determine if windows Forml and Form2 are overlapping on the 

































































" screen. If they don't the intersection rectangle will be empty. 

Dim intrect As RECT ' receives the intersection rectangle 

Dim windowl As RECT, window2 As RECT ' receive rectangles of Forml and Form2 
Dim isempty As Long ' will be set to 0 if intersection isn't empty, 1 if it is 
Dim retval As Long ' return value for other functions 

retval = GetWindowRect (Forml.hWnd, window1) " get Forml's rectangle 

retval = GetWindowRect (Form2.hWnd, window2) " get Form2's rectangle 

retval = IntersectRect (intrect, windowl, window2) ' determine the intersection 
rectangle 

isempty = IsRectEmpty (intrect) ' determine if it is empty -- it will be if there's 
no intersection 

If isempty = 0 ' in this case, intrect will also be empty 


Debug.Print "Windows Forml and Form2 are not overlapping on the screen." 
Else 
Debug.Print "Windows Forml and Form2 are overlapping on the screen." 
End If 











See Also: SetRectEmpty 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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IsWindow Function 


Declare Function IsWindow Lib "user32.d11" (ByVal hWnd As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Desctiption & Usage 


IsWindow determines if a given handle refers to a window or not. The function verifies that the handle in fact 
refers to a window, instead of one of the many other objects which handles can represent. 


Return Value 


If the handle does not refer to a window, the function returns 0. If the handle does refer to a window, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
The handle to check if it refers to a window or not. 


Example 
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' This code is licensed according to the terms and conditions listed here. 





" Demonstrate handles refering to a window and not refering to a window. 


Dim hWindow As Long ' handle to a window (Forml, to be exact) 
Dim hPen As Long ' handle to a pen (the solid black stock pen) 
Dim result As Long ' result of the test 





' Initialize the two handles. 
































hWindow = Forml.hWnd ' hWindow now equals window Forml's handle 
hPen = GetStockObject (BLACK_PEN) ' hPen refers to a pen 
' Verify that hWindow refers to a window. 
result = IsWindow (hWindow) 
If result = 0 Then 
Debug.Print "hWindow does not refer to a window." !' won't happen 
Else 
Debug.Print "hWindow refers to a window." ' will happen 
End If 
' Verify that hPen does not refer to a window. 
result = IsWindow (hPen) 
If result = 0 Then 
Debug.Print "hPen does not refer to a window." ' will happen 
Else 
Debug.Print "hPen refers to a window." ' won't happen 
End If 





See Also 


IsChild 


Category 


Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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IsWindowEnabled Function 


Declare Function IsWindowEnabled Lib "user32.dl1" (ByVal hwnd As Long) 
As Long 


Platforms: Win 32s, Win 95/98, Win NT 


IsWindowEnabled determines if a window is currently enabled or disabled. If a window is disabled, it 
cannot receive the focus and will ignore any attempted input. Many types of windows, such as buttons 
and other controls, will appear grayed when disabled. The function returns 0 if the window is disabled, or 
a non-zero value if the window is enabled. 








hwnd 
A handle to the window to determine if it is enabled or disabled. 
Example: 
" Reverse the enabled status of window Commandl. If the window is 
' disabled, enable it; if it is enabled, disable it. 
Dim wasenabled As Long ' receives enabled/disabled status of Commandl 
Dim retval As Long ' return value 


' Determine if the window Commandl is currently enabled or not. 
wasenabled = IsWindowEnabled (Command1.hWnd) 








If wasenabled = 0 Then ' if not enabled, enable it 
retval = EnableWindow(Commandl.hWnd, 1) 

Else ' if enabled, disable it 
retval = EnableWindow(Commandl.hWnd, 0) 

End If 


See Also: EnableWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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IsZoomed Function 





Declare Function IsZoomed Lib "user32.dll1" (ByVal hwnd As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


IsZoomed finds if a given window is maximized or not. The function returns 0 if the window is not maximized (it 
could be either restored or minimized); it returns a non-zero value if the window is maximized. 


hwnd 
A handle to the window to find whether it is maximized or not. 


Example: 


' Determine if the window Forml is maximized, minimized, or restored. 
































Dim minflag As Long, maxflag As Long ' receive minimized or maximized status 
minflag = IsIconic(Forml1.hWnd) ' is Forml minimized? 

maxflag = IsZoomed (Form1.hWnd) ' is Forml maximized? 

If minflag <> 0 Then 





Debug.Print "Forml is minimized." 
Elseif maxflag <> 0 Then 
Debug.Print "Forml is maximized." 
Else 

Debug.Print "Forml is restored." 
End If 

















See Also: IsIconic, ShowWindow 
Category: Windows 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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joyGetDevCaps Function 


Declare Function joyGetDevCaps Lib "winmm.dll" Alias "JjoyGetDevCapsA" (ByVal 
id As Long, lpCaps As JOYCAPS, ByVal uSize As Long) As Long 


Platforms: Win 95/98 


joyGetDevCaps reads various information about a joystick. This information is put into the variable passed as 
IpCaps. This function does not, however, give you the current position of the joystick. The function returns 0 if the 
joystick is connected and working and a non-zero error code if it isn't. 


id 

The ID number of the joystick to read, starting with 0. 
lpCaps 

Variable that receives the information about the joystick. 
uSize 

The length in bytes of [pCaps. 


Example: 

' Display the name of the joystick driver for Joystick #1 
" Note that the ID of Joystick #1 is 0. 

Dim joyinfo As JOYCAPS ' receives joystick information 








Dim joydriver As String ' will be set to the joystick's driver name 
Dim retval As Long ' return value 


retval = joyGetDevCaps(0, joyinfo, Len(joyinfo) ) ' read joystick information 
If retval = 0 Then ' there is a functioning Joystick #1 

joydriver = Left (joyinfo.szPname, InStr(joyinfo.szPname, vbNullChar) - 1) 
extract data from the fixed-length string 

Debug.Print "The joystick driver is: "; joydriver 
Else 

Debug.Print "There is no joystick connected to Joystick Port #1." 
End If 





Category: Joysticks 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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shop.com | 
joyGetNumDevs Function 
Declare Function joyGetNumDevs Lib "winmm.dll" () As Long 





Platforms: Win 95/98 





joyGetNumDevs returns the number of joysticks that are configured under Windows's Control Panel. This doesn't necessarily 
mean that all of them are connected and in working order, but there could be. The best way to see if a joystick is working is to 
call joyGetDevCaps and check for a return value of 0. 





Example: 


F 





n 














Determine the number of configured joysticks and the number of 


£ 








connected joysticks. To see if a joystick is connected, try to read information 


from it and see if 








the attempt is successful or not. 


























im joyinfo As JOYCAPS ' needed for the function call to see if a joystick works 
im numjoys As Long ' receives number of configured joysticks 

im numexist As Long ' number of existing joysticks hooked up to the computer 

im c As Integer ' counter variable 

im retval As Long ' return value for other functions 

umjoys = joyGetNumDevs () ' determine the number of configured joysticks 


ebug.Print 

















"There are"; numjoys; “joysticks configured under Windows." 




















numexist = 0 ' initialize the number of existing joysticks 
For c = 0 To numjoys - 1 ' check each joystick (remember Joystick #1's ID = 0, etc.) 
retval = joyGetDevCaps(c, joyinfo, Len(joyinfo) ) ' try to read information 
If retval = 0 Then numexist = numexist + 1 ' increment counter if the joystick is 
connected 
Next c 





Debug.Print 


"There are"; numexist; "joysticks currently connected to the computer." 


Category: Joysticks 
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joyGetPos Function 





Declare Function joyGetPos Lib "winmm.dll" 
Long 


Platforms: Win 95/98 


joyGetPos reads the current position and status of a joystick. This information is put into the variable passed as pji. The 
function returns 0 if the joystick is connected and working, or a non-zero error code if it is not. 


uJoyID 
The ID number of the joystick to read, starting at 0. 


pji 








Variable that receives the joystick's current position and status. 


Example: 





' Display the x, y, and z coordinates of Joystick #1, as 


' as the status of buttons 1-4 (which are the only ones this function can read). 








(ByVal uJoyID As Long, 


well 


(remember Joystick #1's ID 


Dim joypos As JOYINFO ' receives current joystick status 
Dim retval As Long ' return value 

retval = joyGetPos(0, joypos) " get the joystick status 
0) 


Debug.Print "X Coordinate:"; pos.wXpos 
Debug.Print "Y Coordinate:"; pos.wYpos 
Debug.Print "Z Coordinate:"; pos.wZpos 














£ 


If (pos.wButtons And JOY_BUTTON1) = JOY_BU 
depressed." 





TTON1 Then Deb 





If (pos.wButtons And JOY_BUTTON2) 
depressed." 


JOY_BU 





TION2 Then Deb 





If (pos.wButtons And JOY_BUTTON3) 
depressed." 


JOY_BU 





TION3 Then Deb 
























































If (pos.wButtons And JOY_BUTTON4) = JOY_BU 
depressed." 


Category: Joysticks 


Go back to the alphabetical Function listing. 
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pji As JOYINFO) 





Button 








ug.Print 








ug.Print 
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keybd_event Function 


Declare Sub keybd_event Lib "user32.dll1" (ByVal bVk As Byte, ByVal bScan 
As Byte, ByVal dwFlags As Long, ByVal dwExtraInfo As Long) 





Platforms 


e Windows 95: Supported. 

e Windows 98: Supported but Obsolete; use SendInput instead. 

e Windows NT: Requires Windows NT 3.1 or later but Obsolete with Windows NT 4.0 with Service 
Pack 3 (SP3) or later; use SendInput instead. 

e Windows 2000: Supported but Obsolete; use SendInput instead. 

e Windows CE: Requires Windows CE 1.0 or later but Obsolete with Windows CE 2.0 or later; use 
SendInput instead. 


Description & Usage 


keybd_event simulates keyboard input by placing a keyboard input event into the input stream. The function 
can simulate a single press or release of a single key. This function should only be used when a key's state 
changes. For example, do not tell the function to simulate pressing the Z key if the Z key is already pressed. 


Return Value 

keybd_event does not return a value. 

Visual Basic-Specific Issues 
None. 


Parameters 


bVk 
The virtual-key code of the key to simulate pressing or releasing. 
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bScan 
Reserved -- set to 0. 
dwFlags 
A combination of the following flags specifying what kind of keyboard input to synthesize: 
KEYEVENTF_EXTENDEDKEY 
Prefix the scan code with a prefix byte having the value & HEO. 
KEYEVENTF_KEYUP 
The key specified in bVk is being released. If this flag is not specified, the key is being pressed. 
dwExtralnfo 
An additional 32-bit value associated with the keyboard event. 


Constant Definitions 





Const KEYEVENTF_EXTENDEDKEY = &H1 
Const KEYEVENTF_KEYUP = &H2 








Example 


' This code is licensed according to the terms and conditions listed here. 


' Simulate the user pressing Alt+Space followed by N. This 
' key combination will minimize the active window. 


' Hold the Alt key while typing Space. 








keybd_event VK_MENU, 0, 0, O ' press Alt 

keybd_event VK_SPACE, 0, 0, O0 ' press Space 

keybd_event VK_SPACE, 0, KEYEVENTF_KEYUP, 0 ' release Space 
keybd_event VK_MENU, 0, KEYEVENTF_KEYUP, 0 ' release Alt 


' Type the N key. 





keybd_event VK_N, 0, 0, O ' press N 
keybd_event VK_N, 0, KEYEVENTF_KEYUP, 0 ' release N 
See Also 


mouse_event, SendInput 





Category 


Keyboard 
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KillTlimer Function 

















Declare Function KillTimer Lib "user32.d11" (ByVal hWnd As Long, ByVal nIDEvent As 
Long) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


KillTimer deactivates and destroys the specified timer. However, it does not remove any existing WM_TIMER messages 
which may still be sitting in a window's message queue, if the timer was configured to do so. Your program should destroy any 
timer created by SetTimer once it is no longer needed. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 
hWnd 


A handle to the window that owns the timer. This must be the same value originally passed to SetTimer. 


ulDEvent 
If the timer was owned by a window, this is the program-defined identifer of the timer. This index was specified in the 
call to SetTimer. If the timer is not owned by any window, this is the value returned by the call to SetTimer. 


Example 


Display the current time in text box control Textl. The time is updated twice every second, and the time is formatted according 
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to the current locale's settings. To use this example, place a text edit box named Text! on a form window. 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 


' (Copy them to 





the 


(declarations) 











Public Type SYSTEMTIME 


wrear As Integer 


wMonth As 











Integer 


wDayOfWeek As Integer 
wDay As Integer 
wHour As Integer 


wMinute As Integer 
wsecond As Integer 
wMilliseconds As Integer 




















Declare Function SetTimer Lib 




















End Type 
Public 

As Long, 
Public 
niDEvent As Long) 
Public Declare Funct 
(ByVal _ 

Locale As 
As Any, _ 





' ***x Place the following code inside a module. 


vag 


' The following 


unction will 


As Long 





section of 


ByVal uElapse As Long, 
Declare Function KillTimer L 


ib 


tion GetTimeFormat Lib 








Long, 


ByVal lpTimeStr As String, 








preferences. 





Public Sub TimerProc (ByVal 

















" Ret riev 


Dim systime As SYS' 


ByVal dwTime As Lon 








TEMT IME 











Dim timestr As String * 260 
Dim slength As Long 


the current time 








GetLocalTime systime 





ByVal dwFlags As Long, 





hwnd As Long, 


g) 


1 





a module.) 





"user32.dqdl1l1" (ByVal 














ByVal cchTime As Long) 


kk*kx* 


execute twice every second. 
' the current time and displays it according to the current 


ByVal lpTimerFunc As Long) 
"user32.dll1" (ByVal hWnd As Long, 


"kernel32.dl1" Alias 


ns and conditions listed here. 











Event 








hWnd As Long, ByVal nI 
As Long 
ByVal 








lpTime As SYSTEMTIME, 








ByVal 


"GetTimeFormatA" 








As Long 


It retrieves 
locale's formatting 








the current time 


ByVal uMsg As Long, 














receives the 


formatted string 














length of 





formatted string returned 


, according to the computer's time zone. 


' Format a string to represent the time. 


slength = 





' Display 


Forml.Textl.Text = 





End Function 


' *** Place the following code inside Forml. 


GetTimeFormat (0, 





0, 


the string in Textl, 





Left (timestr, 


systime, CLng (0), 





slength) 








' Create the timer when the form opens and destroy it when the 
so the return values don't need to be saved. 





' The 


timer is given an ID of 1, 








Private Sub Forml_Load() 


kkk 
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Len (timestr) ) 





found on window Forml. 





form closes. 


lpFormat 


ByVal idEvent As Long, 
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Dim retval As Long ' return value 


retval = SetTimer(Forml.hWnd, 1, 500, AddressOf TimerProc) 
End Sub 











Private Sub Forml_Unload(Cancel As Integer) 
Dim retval As Long ' return value 





retval = KillTimer(Forml.hWnd, 1) 
End Sub 





See Also 


SetTimer 


Category 


Timers 


Back to the Function list. 





Back to the Reference section. 


Last Modified: December 17, 2000 
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LineTo Function 


Declare Function LineTo Lib "gdi32.dl11" (ByVal hdc As Long, ByVal x As Long, ByVal y 
As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


LineTo draws a line from the current point to the point specified on a device. The line is drawn in the color specified by that 
object's .ForeColor property. After the line is drawn, the endpoint is the new current point. The algorithm Windows uses to 
draw a line does not actually color the last pixel of the line because it is not considered part of the line. The function returns 0 
if an error occured, or 1 if successful. 


g The device context of the device to draw on. 
i The x coordinate of the endpoint to draw to. 
i The y coordinate of the endpoint to draw to. 
Example: 


' Draw a red line from (0,40) to (100,50) on the window Forml. 





























Dim pt As POINT TYPE ' needed for another API function 

Dim retval As Long ' return value 

Forml.ForeColor = RGB(255, 0, 0) ' set the foreground drawing color of Forml to red 
retval = MoveToEx(Forml.hdc, 0, 40, pt) ' set the current point to (0,40) 

retval = LineTo(Forml.hdc, 100, 50) ' draw a line from current point to (100,50) 





See Also: Polyline, PolylineTo, PolyPolyline 
Category: Lines & Curves 








Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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LoadCursor Function 


Declare Function LoadCursor Lib "user32.d1l1" Alias "LoadCursorA" (ByVal 
hInstance As Long, ByVal lpCursorName As Any) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


LoadCursor loads a cursor from either a currently running program's cursor resources or Windows's cursor 
resources. The cursor can be referenced either by its resource name or by its numeric resource ID number. If 
successful, the function returns a handle to the loaded cursor. If unsuccessful, the function returns 0. 


hInstance 
To load one of a program's cursor resources, set this to the application's instance handle. To load one of 
Windows's cursor resources, set this to 0. 
lpCursorName 
Either a string containing the name of the cursor resource to load, or a numeric ID number identifying the 
resource. For Windows's cursors, exactly one of the following flags can be used to select the desired cursor 
resource: 
IDC_APPSTARTING = 32650 
The application starting cursor (arrow and hourglass). 
IDC_ARROW = 32512 
The regular arrow pointer cursor. 
IDC_CROSS = 32515 
The cross cursor. 
IDC_IBEAM = 32513 
The I-shaped beam cursor (text editing cursor). 
IDC_ICON = 32641 
Win NT only: An empty cursor. 
IDC_NO = 32648 
The "no" symbol cursor (circle with a slash). 
IDC_SIZE = 32640 
Win NT only: The four-pointed resize/move arrow. 
IDC_SIZEALL = 32646 
The four-pointed resize/move arrow. 
IDC_SIZENESW = 32643 
The double-pointed resize arrow pointing to the upper-right and lower-left. 
IDC_SIZENS = 32645 
The double-pointed resize arrow pointing up and down. 
IDC_SIZENWSE = 32642 
The double-pointed resize arrow pointing to the upper-left and lower-right. 
IDC_SIZEWE = 32644 
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The double-pointed resize arrow pointing left and right. 
IDC_UPARROW = 32516 

The up-arrow cursor. 
IDC_WAIT = 32514 

The wait cursor (hourglass). 


Example: 


' Display the application starting (arrow and hourglass) Windows 











" cursor for three seconds. The cursor resource is loaded from Windows. Then 
' restore the old cursor (whatever it happens to be). 

Dim hcursor As Long ' receives handle to application starting cursor 

Dim holdcursor As Long ' receives handle to previously used cursor 

Dim retval As Long ' throw-away return value 

hcursor = LoadCursor(0, IDC_APPSTARTING) ' load Windows's application starting 
cursor 

holdcursor = SetCursor(hcursor) ' set it to the new cursor 


Sleep 3000 ' wait for 3 seconds 
retval = SetCursor(holdcursor) ' set it to the previous cursor 


See Also: LoadCursorFromFile 
Category: Cursor 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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LoadCursorFrom File Function 





Declare Function LoadCursorFromFile Lib "user32.d1l1" Alias "LoadCursorFromFileA" 
(ByVal lpFileName As String) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


LoadCursorFromFile loads a cursor from a cursor file. The cursor file can contain either a regular cursor (*.cur) or an 
animated cursor (*.ani). If successful, the function returns a cursor handle to the newly loaded cursor. If unsuccessful, the 
function returns 0. 


IpFileName 
The filename of the cursor file to load. This file can either be a *.cur or an *.ani cursor file. 


Example: 


' Load the cursor "C:\MyProg\custom.ani" and set it as 









































" the current cursor for three seconds. Then restore the original cursor as 

' the current cursor. 

Dim hcursor As Long ' receives handle to the loaded cursor 

Dim holdcursor As Long ' receives handle to the previously in use cursor 

Dim retval As Long ' throw-away return value 

hcursor = LoadCursorFromFile ("C:\MyProg\custom.ani") ' load the animated cursor from 
the file 

If hcursor = 0 Then End ' abort program if cursor couldn't be loaded 
holdcursor = SetCursor(hcursor) " set the loaded cursor as the current cursor 
Sleep 3000 ' wait for three seconds 

retval = SetCursor (holdcursor) " restore the previous cursor 


See Also: LoadCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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LocalFileTimeToFileTime Function 


Declare Function LocalFileTimeToFileTime Lib "kernel32.d11" 
(lpLocalFileTime As FILETIME, lpFileTime As FILETIME) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


LocalFileTimeToFileTime converts a time from local time (time according to the computer's current 
time zone) to UTC time (also known as Greenwich Mean Time). The source and target times are stored 
in FILETIME format. The function returns 1 if successful, or O if an error occured. 


lpLocalFileTime 
The time and date in local time to convert. 
lpFileTime 
Receives the time and date specified in JpLocalFileTime converted to UTC time. 


Example: 
" Convert the time and date May 1, 1999 6:10:00 PM local time 


" to a FILETIME structure in UTC time. 
Dim sourcetime As SYSTEMTIME ' original time and date 





Dim localtime As FILETIME " receives sourcetime's time 
Dim utctime As FILETIME " receives the final result 


Dim retval As Long ' return value 


' Set sourcetime to the desired date: 
sourcetime.wMonth = 5: sourcetime.wDay = 1: sourcetime.wYear = 1999 
sourcetime.wHour = 18: sourcetime.wMinute = 10: sourcetime.wSecond = 0 








" Convert sourcetime into FILETIME format: 
retval = SystemTimeToFileTime (sourcetime, localtime) 





" Convert localtime into UTC time: 
retval = LocalFileTimeToFileTime(localtime, utctime) 
' utctime now has the converted time and date 
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See Also: FileTimeToLocalFileTime 
Category: Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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LockWorkStation Function 


Declare Function LockWorkStation Lib "user32.dll" () As Long 


Platforms 


Windows 95: Not Supported. 
Windows 98: Not Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Description & Usage 


LockWorkStation locks the computer, preventing anybody from entering input until either the user who 
locked it or an administrator enters his or her password. This function does the same thing as though the user 
had pressed Ctrl+Alt+Del and selected "Lock Workstation." 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 
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Lock the workstation when the user clicks the command button named cmdLock. Obviously, to use this 
example, you must place a command button named cmdLock on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function LockWorkStation Lib "user32.dl1l" () As Long 











' **x* Place the following code inside the form window. *** 


Private Sub cmdLock_Click () 
" Lock the workstation when this button is clicked. 





Dim retval As Long ' return value 


retval = LockWorkStation () 
' That's all there is to it! 
End Sub 


Category 
Shutdown 


Back to the Function list. 
Back to the Reference section. 





Last Modified: December 17, 2000 
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Istrcmp Function 


Declare Function lstremp Lib "kernel32.d1l1" Alias "l1strcmpA" (ByVal 
lpStringl As String, ByVal lpString2 As String) As Long 


Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Istrcemp compares two strings using a case-sensitive comparison based on the current user locale. The function 
uses a word sort method, which places all symbols except hyphens and apostrophes before the letter "a" 
(hyphens and apostrophes are treated differently). The strings are compared by comparing the first character of 
each string, then the second character, etc., until unequal characters are encountered. 


Return Value 


If the function returns a negative value, the first string is less than the second string (i.e., the first string comes 
before the second string in alphabetical order). If the function returns 0, the two strings are equal. If the 
function returns a positive value, the first string is greater than the second string. In any case, the actual return 
value is the difference of the first unequal characters encountered. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpString1 
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The first string to compare. 
IpString2 
The second string to compare. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Use a case-senitive comparison method to alphabetically sort 

" nine words. The sorting method simply compares each possible pair 

' of words; if a pair is out of alphabetical order, they are switched. 
Dim words(l To 9) As String ' the words to sort 

Dim tempstr As String ' buffer used to swap strings 

oc As Integer, ic As Integer ' counter variables 





Dim 

















Dim compval As Long ' result of comparison 
' Load the nine strings into the array. 
words(l) = "can't" 
words(2) = "cant" 
words (3) = "cannot" 
words (4) = "pants" 
words (5) = "co-op" 
words (6) = "coop" 
words(7) = "Denver" 
words(8) = "denver" 
words(9) = "denveR" 
' Sort the strings, swapping any pairs which are out of order. 
For oc = 1 To 8 ' first string of the pair 
For ic = oc + 1 To 9 ' second string of the pair 


" Compare the two strings. 


compval 
' If words (oc) 





lstremp (words (oc), 
is greater, swap them. 





If compval > 0 Then 
tempstr = words (oc) 
words (oc) = words (ic) 
words(ic) = tempstr 
End If 
Next ic 
Next oc 
' Display the list of sorted words. 
For oc = 1 To 9 





Next oc 


Debug.Print words (oc) 
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See Also 


CompareString, Istrempi 





Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: December 30, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
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Istrcmpi Function 


Declare Function lstrempi Lib "kernel32.d1l1" Alias "lstrcmpiA" (ByVal 
lpStringl As String, ByVal lpString2 As String) As Long 


Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Istrcmpi compares two strings using a case-insensitive comparison based on the current user locale. The 
function uses a word sort method, which places all symbols except hyphens and apostrophes before the letter 
"a" (hyphens and apostrophes are treated differently). The strings are compared by comparing the first 
character of each string, then the second character, etc., until unequal characters are encountered. 


Return Value 


If the function returns a negative value, the first string is less than the second string (i.e., the first string comes 
before the second string in alphabetical order). If the function returns 0, the two strings are equal. If the 
function returns a positive value, the first string is greater than the second string. In any case, the actual return 
value is the difference of the first unequal characters encountered. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpString1 
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The first string to compare. 
IpString2 
The second string to compare. 


Example 


Use a case-insenitive comparison method to alphabetically sort 


This code is licensed according to the terms and conditions listed here. 


nine words. The sorting method simply compares each possible pair 


' of words; if a pair is out of alphabetical order, they are switched. 


(Note how this sort will seemingly arrange the "Denver" trio in 
' a random order, depending on how the search loops play out -- 





Fore 





' the three strings are equal in the eyes of the function and there] 
" not sorted relative to each other.) 

Dim words(l1 To 9) As String ' the words to sort 

Dim tempstr As String ' buffer used to swap strings 

Dim oc As Integer, ic As Integer ' counter variables 

Dim compval As Long ' result of comparison 











' Load the nine strings into the array. 





words(l) = "can't" 
words(2) = "cant" 

words(3) = "cannot" 
words (4) = "pants" 
words(5) = "co-op" 
words (6) = "coop" 

words(7) = "Denver" 
words(8) = "denver" 
words(9) = "denveR" 





' Sort the strings, swapping any pairs which are out of order. 
For oc = 1 To 8 ' first string of the pair 
For ic = oc + 1 To 9 ' second string of the pair 
" Compare the two strings. 
compval = lstrempi (words (oc), words (ic) ) 
' If words(oc) is greater, swap them. 
If compval > 0 Then 














tempstr = words (oc) 
words (oc) = words (ic) 
words (ic) = tempstr 
End If 
Next ic 
Next oc 
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' Display the list of sorted words. 
For oc = 1 To 9 

Debug.Print words (oc) 

Next oc 





See Also 


CompareString, Istrcmp 


Category 


Strings 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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Istrcpy Function 


Declare Function lstrcepy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 
As Any, ByVal lpString2 As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Istrepy copies the entire contents of one string into another string. Either string, instead of being a "real" string, can 
also be merely a pointer to a string instead. The target string must already have enough space to receive the source 
string's contents. The function also will copy a terminating null character into the target string. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


This function is very useful for "converting" a pointer to a string into an actual string. 


Parameters 


IpString1 
String that receives the copied contents of /pString2. This could be either the string itself or a pointer to the 
string. 

IpString2 
Either an actual string to copy into /pString/ or a pointer to the string to copy into /pString 1. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Copy the source string to the target string 


Dim source As String, target As String ' the two strings 

Dim retval As Long ' return value 

source = "Hello, world!" ' the source string to copy 

target = Space(Len(source) ) ' make room in target to receive the copied string 
retval = lstrepy (target, source) ' set target to equal source 

Debug.Print "Source string: "; source 

Debug.Print "Target string: "; target ' they should be the same.... 


See Also 


Istrcpyn 


Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: December 22, 1999 
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Istrcpy Function 


Declare Function lstrcpyn Lib "kernel32.d11" Alias "lstrcpynA" (ByVal lpStringl 
As Any, ByVal lpString2 As Any, ByVal iMaxLength As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Istrepy copies one or more characters from one string into another string, followed by a terminating null character. 
Either string, instead of being a "real" string, can also be merely a pointer to a string instead. The target string must 
already have enough space to receive the source string's contents along with the terminating null. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


This function is very useful for "converting" a pointer to a string into an actual string. 


Parameters 


IpString1 
String that receives the copied contents of /pString2. This could be either the string itself or a pointer to the 
string. 

IpString2 
Either an actual string to copy into /pString/ or a pointer to the string to copy into /pString 1. 

iMaxLength 
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The number of characters to copy from /pString2 to [pString/, including the terminating null character added 
to the end. (For example, a value of 4 for this parameter would copy three characters from /pString2 and a null 
character into IpString1. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Copy the first word source string to the target string 


Dim source As String, target As String ' the two strings 

Dim retval As Long ' return value 

source = "Hello, world!" ' the source string to copy 

target = Space (6) ' make room in target to receive the copied string 

retval = lstrepy(target, source, 6) ' set target to equal source 

target = Left (target, Len(target) - 1) ' remove the terminating null character 
Debug.Print "Source string: "; source 

Debug.Print "Target string: "; target ' this should be "Hello" 


See Also 


Istrcpy 


Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: December 26, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/I/lstrcpyn.html 
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Istrien Function 


Declare Function Istrlen Lib "kernel32.d11" Alias "l1strlenA" (ByVal 
lpString As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


Istrlen determines the length of a string. The length of a string is considered to be the number of characters it 
contains, not counting any possible terminating null character. This function can also determine the length of a 
string to which a pointer refers. 


Return Value 


The function returns the length of the string, measured in number of characters. 


Visual Basic-Specific Issues 


This function is very useful, in conjunction with Istrcpy, for "converting" a pointer to a string into an actual 
string. 


Parameters 


lpString 
Either the string to determine the length of or a pointer to the string to determine the length of. 
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' This code is licensed according to the terms and conditions listed here. 





' Display the length of the string "Hello, world!" 











Dim slength As Long ' receives the length of the string 
slength = lstrlen("Hello, world!") ' find the length of the string 
Debug.Print "The string 'Hello, world!' contains"; slength; "characters." 


Category 


Strings 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: December 21, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/I/lstrlen.html 
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mciSendString Function 

















Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" (ByVal 
fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) As Long 





























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


mciGetErrorString obtains a textual description of an error raised by another Media Control Interface (MCI) function. 
Typically these errors are not the fault of the program. Rather, they are caused by "problems" with the device (for example, the 
MIDI driver is currently being used by another program, so your program's attempt to open it failed). The messages retrieved 
by this function are sufficient to tell the user what caused the error. 


Return Value 


If successful, the function returns a nonzero value. If an error occured, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


fdwError 
A MCI error code returned by another MCI function. mciGetErrorString gets a description of this error. 
lpszErrorText 
A string that receives a textual description of the error terminated by a null character. This string must already contain 
enough room to receive the text. This string should be at least 128 characters long. 
cchErrorText 
The length of the string passed as /pszErrorText. 


Example 
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To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 





















































Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 
lpszCommand As String, ByVal lpszReturnString As String, ByVal 
cchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 
Public Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
(ByVal _ 
fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 
As Long 


Use the MCI to play or stop playback of 
is opened when the form opens. 
The 

' only potential surprise is that the current position is not reset when playback 
stops; it 

' behaves just as pausing playback would. 














a MIDI file. The file C:\Music\canyon.mid 
The Play and Stop buttons behave as you'd expect. 





The file closes when the form unloads. 




















































































































' Tf anything goes wrong in the example, display a message box with 
' the MCI error message text. 
Private Sub Form_Load() 
' Open the file "C:\Music\canyon.mid" for later use in the example. 
' Give it an alias of "canyon" so we don't need to refer to the filename 
again. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 
Private Sub cmdPlay_Click () 
' Begin playback of the MIDI file when this button is pressed. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("play canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 
Private Sub cmdStop_Click () 
' Stop playback of the MIDI file when this button is pressed. 
' The position within the file does not move back to the beginning. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("stop canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 
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Private Sub Form_Unload(Cancel As Integer) 
' Close the MIDI file when the 



























































form unloads. 


This is important, because the 



































' MIDI driver can only work with one file at a time. There's no need to 
check 

' for an error here, since we're just closing the file. 

Dim errcode As Long ' MCI error code 

errcode = mciSendString("close canyon", "", 0, 0) 
End Sub 
Private Sub DisplayError (ByVal errcode As Long) 

' This subroutine displays a dialog box with the text of the MCI error. 
There's 

' no reason to use the MessageBox API function; VB's MsgBox function will 
suffice. 

Dim errstr As String ' MCI error message text 

Dim retval As Long ' return value 

' Get a string explaining the MCI error. 

errstr = Space(128) 

retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 

' Remove the terminating null and empty space at the end. 

errstr = Left(errstr, InStr(errstr, vbNullChar) - 1) 

' Display a simple error message box. 

retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 





See Also 


mciSendString 


Category 


Media Control Interface (MCI) 





Back to the Function list. 
Back to the Reference section. 





Last Modified: July 4, 2000 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/m/mcigeterrorstring.html 
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mciSendString Function 
Declare Function mciSendString Lib "winmm.dl1l" Alias "mciSendStringA" (ByVal 











lpszCommand As String, ByVal lpszReturnString As String, ByVal cchReturnLength As 
Long, ByVal hwndCallback As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


mciSendString sends a command to a Multimedia Control Interface (MCI) device. The command strings used with this 
function can perform almost any task necessary for using a multimedia device installed on the computer. mciSendString 
provides a relatively easy way to perform multimedia output operations. 


Look at the MCI command strings page for a list of some of the command strings used by the mciSendString function. 


Return Value 


If successful, the function returns 0. If an error occured, the function returns a nonzero MCI error code. To get a textual 
description of the error, use the mciGetErrorString function. 





Visual Basic-Specific Issues 


None. 


Parameters 


lpszCommand 
The command string to execute, including all of its necessary parameters and desired options. 

IpszReturnString 
For command strings that return information, this string receives the data output by the command. This string must 
initially be at least 128 characters long in order to receive the string. Any information placed into this string will be null- 
terminated. If the command string does not return any information, this parameter is ignored. 

cchReturn 
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The length of the string passed as /pszReturnString. 

hwndCallback 
If the "notify" flag of the command string is specified, this is a handle to the window to receive a MM_MCINOTIFY 
message when the command has completed, no matter whether it succeeded or failed. 





Example 


To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 

lpszCommand As String, ByVal lpszReturnString As String, ByVal 
cchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 

ublic Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
ByVal _ 

















ry 























~ 























fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 
As Long 














' Use the MCI to play or stop playback of a MIDI file. The file C:\Music\canyon.mid 
' is opened when the form opens. The Play and Stop buttons behave as you'd expect. 
The 

' only potential surprise is that the current position is not reset when playback 
stops; it 

' behaves just as pausing playback would. The file closes when the form unloads. 

















' If anything goes wrong in the example, display a message box with 
' the MCI error message text. 





Private Sub Form_Load() 























' Open the file "C:\Music\canyon.mid" for later use in the example. 
' Give it an alias of "canyon" so we don't need to refer to the filename 
again. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString ("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 





Private Sub cmdPlay_Click () 
' Begin playback of the MIDI file when this button is pressed. 

















Dim errcode As Long ' MCI error code 
errcode = mciSendString("play canyon", "", 0, 0) 














If errcode <> 0 Then DisplayError errcode 
End Sub 





Private Sub cmdStop_Click () 
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' Stop playback of the MIDI file when this button is pressed. 
' The position within the file does not move back to the beginning. 














Dim errcode As Long ' MCI error code 
errcode = mciSendString("stop canyon", "", 0, 0) 








If errcode <> 0 Then DisplayError errcode 
End Sub 





Private Sub Form_Unload(Cancel As Integer) 

















' Close the MIDI file when the form unloads. This is important, because the 
' MIDI driver can only work with one file at a time. There's no need to 
check 
' for an error here, since we're just closing the file. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("close canyon", "", 0, 0) 
End Sub 














Private Sub DisplayError (ByVal errcode As Long) 
' This subroutine displays a dialog box with the text of the MCI error. 





There's 











" no reason to use the MessageBox API function; VB's MsgBox function will 
suffice. 





Dim errstr As String ' MCI error message text 
Dim retval As Long " return value 





' Get a string explaining the MCI error. 
errstr = Space(128) 
retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 














' Remove the terminating null and empty space at the end. 
errstr = Left(errstr, InStr(errstr, vbNullChar) - 1) 














' Display a simple error message box. 
retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 














See Also 


mceiGetErrorString 





Category 


Media Control Interface (MCI) 


Back to the Function list. 





Back to the Reference section. 





Last Modified: July 4, 2000 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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MessageBeep Function 


Declare Function MessageBeep Lib "user32.dll1" (ByVal wType As Long) As 
Long 


Platforms: Win 32s, Win 95/98, Win NT 


MessageBeep plays one of the system's associated sounds, with one exception. These sounds are some of 
the ones that Windows associates with certain events. However, this function can also play a beep on the 
computer's internal speaker. The function returns 1 if successful, or 0 if an error occured. 


wType 
If set to -1 (or & HFFFFFFFF), plays a beep using the computer's internal speaker. Otherwise, this 
is exactly one of the following flags specifying which sound to play: 
MB_ICONASTERISK = &H40 
Play the SystemAsterisk sound. 
MB_ICONEXCLAMATION = &H30 
Play the SystemExclamation sound. 
MB_ICONHAND = &H10 
Play the SystemHand sound. 
MB_ICONQUESTION = &H20 
Play the SystemQuestion sound. 
MB_OK = &H0 
Play the SystemDefault sound. 


Example: 


' Play the SystemQuestion sound. 
Dim retval As Long ' return value 


retval = MessageBeep (MB_ICONQUESTION) ' play the SystemQuestion sound 


See Also: Beep 
Category: Errors 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/m/messagebeep.html 


http://216.26.168.92/vbapi/ref/m/messagebeep.html (2 of 2) [9/1/2002 5:35:34 PM] 


Windows API Guide: MessageBox Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





MessageBox Function 





Declare Function MessageBox Lib "user32.d11" Alias "MessageBoxA" (ByVal hWnd As 
Long, ByVal lpText As String, ByVal lpCaption As String, ByVal uType As Long) As 
Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


MessageBox opens and operates a small message box on the screen. Message boxes are typically used either to 
communicate important information (such as an error message) or to prompt the user. The message box only closes when 
the user presses one of the buttons presented. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one 
of the following flags specifying the button the user clicked on: 


IDABORT 
The Abort button was clicked. 
IDCANCEL 
The Cancel button was clicked (or the user dismissed the message box using the Esc key). 
IDCONTINUE 
Windows 2000: The Continue button was clicked. 
IDIGNORE 
The Ignore button was clicked. 
IDNO 
The No button was clicked. 
IDOK 
The OK button was clicked. 
IDRETRY 
The Retry button was clicked. 
IDTRYAGAIN 
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Windows 2000: The Try Again button was clicked. 
IDYES 
The Yes button was clicked. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window opening the message box. 
IpText 
The text to display inside the message box. 
lpCaption 
The text to display inside the caption area of the message box's title bar. 
uType 
A combination of various flags specifying the behavior and appearance of the message box. The available flags are 
grouped according to function. If no flags in a certain group are specified, the default is used. 


Use one of the following flags to specify which buttons to display in the message box. (Note that MB_HELP can 
be combined with any of the other flags.) 
MB_ABORTRETRYIGNORE 
The message box contains the Abort, Retry, and Ignore buttons. 
MB_CANCELTRYCONTINUE 
Windows 2000: The message box contains the Cancel, Try Again, and Continue buttons. This is meant to 
replace the MB_-ABORTRETRYIGNORE flag. 
MB_HELP 
Windows 95, 98, NT 4.0 or later, 2000: Add the Help button to the message box. When the user clicks the 
Help button, the WM_HELP message is sent to the owner of the message box (specified by the hWnd 
parameter). This flag can only be used by combining it with another button flag (i.e., the Help button cannot 
appear alone). 
MB_OK 
The message box contains the OK button. This is the default. 
MB_OKCANCEL 
The message box contains the OK and Cancel buttons. 
MB_RETRYCANCEL 
The message box contains the Retry and Cancel buttons. 
MB_YESNO 
The message box contains the Yes and No buttons. 
MB_YESNOCANCEL 
The message box contains the Yes, No, and Cancel buttons. 


Use one of the following flags to specify which icon to display in the message box: 
MB_ICONASTERISK, MB_ICONINFORMATION 

Display the information icon: a lowercase letter "i" inside a blue circle. 
MB_ICONERROR, MB_ICONHAND, MB_ICONSTOP 


Display the stop-sign icon in the message box. 
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MB_ICONEXCLAMATION, MB_ICONWARNING 

Display the exclamation-point icon in the message box. 
MB_ICONQUESTION 

Display the question-mark icon in the message box. 


Use one of the following flags to specify which button is selected by default: 
MB_DEFBUTTONI1 

The first button is the default. This is the default. 
MB_DEFBUTTON2 

The second button is the default. 
MB_DEFBUTTON3 

The third button is the default. 
MB_DEFBUTTON4 

The fourth button is the default. 


Use one of the following flags to specify the modality of the message box: 

MB_APPLMODAL 
The message box is application-modal. The user cannot switch to any other windows owned by the 
application until he or she first closes the message box. This is the default. 

MB_SYSTEMMODAL 
The message box is system-modal. The user cannot switch to any other windows until he or she first closes 
the message box. 

MB_TASKMODAL 
The message box is thread-modal. The user cannot switch to any other windows owned by the calling thread 
until he or she first closes the message box. 


Use zero or more of the following flags to specify other options for the message box: 
MB_DEFAULT_DESKTOP_ONLY 
Windows NT, 2000: Same as MB_SERVICE_ NOTIFICATION, except that the system will display the 
message box only on the interactive window station's default desktop. 
MB_RIGHT 
The text in the message box is right-justified. 
MB_RTLREADING 
Display the message text and caption using right-to-left reading order if desired by the system language. 
MB_SETFOREGROUND 
Make the message box the foreground window. 
MB_TOPMOST 
Make the message box a topmost window. 
MB_SERVICE_NOTIFICATION 
Windows NT 4.0 or later, 2000: The calling thread is a service notifying the user of an event. The hWnd 
parameter must be 0. 
MB_SERVICE_NOTIFICATION_NT3X 
Windows NT 3.1 through 3.51: Same as MB_SERVICE_NOTIFICATION. The value of this flag changed 
with the release of NT 4.0. 


Constant Definitions 





Const IDABORT = 3 
Const IDCANCEL = 2 
Const IDCONTINUE = 
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Const IDIGNORE = 5 

Const IDNO = 7 

Const IDOK = 1 

Const IDRETRY = 4 

Const IDTRYAGAIN = 4 

Const IDYES = 6 

Const MB _ABORTRETRYIGNORE = &H2 
Const MB CANCELTRYCONTINUE = &H2 
Const MB_ HELP = &H4000 

Const MB_OK = &HO 

Const MB _OKCANCEL = &H1 

Const MB RETRYCANCEL = &H5 
Const MB _YESNO = &H4 

Const MB_YESNOCANCEL = &H3 
Const MB _ICONASTERISK = &H40 
Const MB _ICONERROR = &H10 

Const MB _ICONEXCLAMATION = &H30 
Const MB _ICONHAND = &H10 

Const MB _ICONINFORMATION = &H40 
Const MB_ICONQUESTION = &H20 
Const MB _ICONSTOP = &H10 

Const MB _ICONWARNING = &H30 
Const MB DEFBUTTONI1 = &H0O 

Const MB DEFBUTTON2 = &H100 
Const MB DEFBUTTON3 = &H200 
Const MB DEFBUTTON4 = &H300 
Const MB APPLMODAL = &H0O 

Const MB _SYSTEMMODAL = &H1000 
Const MB _TASKMODAL = &H2000 
Const MB DEFAULT DESKTOP_ONLY = &H20000 
Const MB_ RIGHT = &H80000 

Const MB RTLREADING = &H100000 
Const MB _SETFOREGROUND = &H10000 








"Const MB TOPMOST = ??? 
"Const MB SERVICE NOTIFICATION = ??? 
"Const MB SERVICE NOTIFICATION _NT3X = ??? 





























Example 


' This code is licensed according to the terms and conditions listed here. 
' Display a warning message box with the Yes and No option 

" owned by window Forml. Make the message box system-modal to force the 
' user to reply immediately. Have "No" selected by default. 

Dim mbresult As Long ' result of message box 

Dim flags As Long ' message box flags 

















' For convenience, use a variable to represent the flag settings. 
flags = MB_YESNO Or MB_ICONWARNING Or MB_DEFBUTTON2 Or MB_SYSTEMMODAL 
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' Display the message box. 





mbresult = MessageBox (Forml.hWnd, "Are you sure you want to do that?", 


flags) 


' Determine what the user pressed. 


If mbresult 
Debug.Prin 





t 














IDYES Then 
"OK, go ahead and do that." 





Elseif mbresult = IDNO Then 





Debug.Prin 
End If 





See Also 


t 








"Operation aborted." 


MessageBoxEx, MessageBoxIndirect 





Category 


Dialog Boxes 


Back to the Function list. 





Back to the Reference section. 


Last Modified: January 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/m/messagebox.html 
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MessageBoxEx Function 





Declare Function MessageBoxEx Lib "user32.d11" Alias "MessageBoxExA" (ByVal hWnd 
As Long, ByVal lpText As String, ByVal lpCaption As String, ByVal uType As Long, 
ByVal wLanguageId As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


MessageBoxEx opens and operates a small message box on the screen. Message boxes are typically used either to 
communicate important information (such as an error message) or to prompt the user. The message box only closes when 
the user presses one of the buttons presented. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one 
of the following flags specifying the button the user clicked on: 


IDABORT 
The Abort button was clicked. 
IDCANCEL 
The Cancel button was clicked (or the user dismissed the message box using the Esc key). 
IDCONTINUE 
Windows 2000: The Continue button was clicked. 
IDIGNORE 
The Ignore button was clicked. 
IDNO 
The No button was clicked. 
IDOK 
The OK button was clicked. 
IDRETRY 
The Retry button was clicked. 
IDTRYAGAIN 
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Windows 2000: The Try Again button was clicked. 
IDYES 
The Yes button was clicked. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window opening the message box. 
IpText 
The text to display inside the message box. 
lpCaption 
The text to display inside the caption area of the message box's title bar. 
uType 
A combination of various flags specifying the behavior and appearance of the message box. The available flags are 
grouped according to function. If no flags in a certain group are specified, the default is used. 


Use one of the following flags to specify which buttons to display in the message box. (Note that MB_HELP can 
be combined with any of the other flags.) 
MB_ABORTRETRYIGNORE 
The message box contains the Abort, Retry, and Ignore buttons. 
MB_CANCELTRYCONTINUE 
Windows 2000: The message box contains the Cancel, Try Again, and Continue buttons. This is meant to 
replace the MB_-ABORTRETRYIGNORE flag. 
MB_HELP 
Windows 95, 98, NT 4.0 or later, 2000: Add the Help button to the message box. When the user clicks the 
Help button, the WM_HELP message is sent to the owner of the message box (specified by the hWnd 
parameter). This flag can only be used by combining it with another button flag (i.e., the Help button cannot 
appear alone). 
MB_OK 
The message box contains the OK button. This is the default. 
MB_OKCANCEL 
The message box contains the OK and Cancel buttons. 
MB_RETRYCANCEL 
The message box contains the Retry and Cancel buttons. 
MB_YESNO 
The message box contains the Yes and No buttons. 
MB_YESNOCANCEL 
The message box contains the Yes, No, and Cancel buttons. 


Use one of the following flags to specify which icon to display in the message box: 
MB_ICONASTERISK, MB_ICONINFORMATION 

Display the information icon: a lowercase letter "i" inside a blue circle. 
MB_ICONERROR, MB_ICONHAND, MB_ICONSTOP 


Display the stop-sign icon in the message box. 
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MB_ICONEXCLAMATION, MB_ICONWARNING 

Display the exclamation-point icon in the message box. 
MB_ICONQUESTION 

Display the question-mark icon in the message box. 


Use one of the following flags to specify which button is selected by default: 
MB_DEFBUTTONI1 

The first button is the default. This is the default. 
MB_DEFBUTTON2 

The second button is the default. 
MB_DEFBUTTON3 

The third button is the default. 
MB_DEFBUTTON4 

The fourth button is the default. 


Use one of the following flags to specify the modality of the message box: 

MB_APPLMODAL 
The message box is application-modal. The user cannot switch to any other windows owned by the 
application until he or she first closes the message box. This is the default. 

MB_SYSTEMMODAL 
The message box is system-modal. The user cannot switch to any other windows until he or she first closes 
the message box. 

MB_TASKMODAL 
The message box is thread-modal. The user cannot switch to any other windows owned by the calling thread 
until he or she first closes the message box. 


Use zero or more of the following flags to specify other options for the message box: 
MB_DEFAULT_DESKTOP_ONLY 
Windows NT, 2000: Same as MB_SERVICE_ NOTIFICATION, except that the system will display the 
message box only on the interactive window station's default desktop. 
MB_RIGHT 
The text in the message box is right-justified. 
MB_RTLREADING 
Display the message text and caption using right-to-left reading order if desired by the system language. 
MB_SETFOREGROUND 
Make the message box the foreground window. 
MB_TOPMOST 
Make the message box a topmost window. 
MB_SERVICE_NOTIFICATION 
Windows NT 4.0 or later, 2000: The calling thread is a service notifying the user of an event. The hWnd 
parameter must be 0. 
MB_SERVICE_NOTIFICATION_NT3X 
Windows NT 3.1 through 3.51: Same as MB_SERVICE_NOTIFICATION. The value of this flag changed 
with the release of NT 4.0. 
wLanguageld 
A language identifier, created by MAKELANGID, which identifies the language used to display the message box's 
buttons. The specified language must be installed on the system. 


Constant Definitions 
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Const IDABORT = 3 

Const IDCANCEL = 2 

Const IDCONTINUE = 5 

Const IDIGNORE = 5 

Const IDNO = 7 

Const IDOK = 1 

Const IDRETRY = 4 

Const IDTRYAGAIN = 4 

Const IDYES = 6 

Const MB ABORTRETRYIGNORE = &H2 
Const MB CANCELTRYCONTINUE = &H2 
Const MB HELP = &H4000 

Const MB_OK = &HO 

Const MB _OKCANCEL = &H1 

Const MB RETRYCANCEL = &H5 
Const MB _YESNO = &H4 

Const MB_YESNOCANCEL = &H3 
Const MB _ICONASTERISK = &H40 
Const MB _ICONERROR = &H10 

Const MB _ICONEXCLAMATION = &H30 
Const MB _ICONHAND = &H10 

Const MB _ICONINFORMATION = &H40 
Const MB_ICONQUESTION = &H20 
Const MB_ICONSTOP = &H10 

Const MB ICONWARNING = &H30 
Const MB DEFBUTTONI1 = &H0O 

Const MB DEFBUTTON2 = &H100 
Const MB DEFBUTTON3 = &H200 
Const MB DEFBUTTON4 = &H300 
Const MB APPLMODAL = &H0O 

Const MB_SYSTEMMODAL = &H1000 
Const MB _TASKMODAL = &H2000 
Const MB DEFAULT DESKTOP_ONLY = &H20000 
Const MB RIGHT = &H80000 

Const MB _RTLREADING = &H100000 
Const MB SETFOREGROUND = &H10000 











"Const MB TOPMOST = ??? 
"Const MB SERVICE NOTIFICATION = ??? 
"Const MB SERVICE NOTIFICATION _NT3X = ??? 


























Example 





' This code is licensed according to the terms and conditions listed here. 











Display a warning message box with the Yes and No option 

" owned by window Forml. Make the message box system-modal to force the 
user to reply immediately. Have "No" selected by default, and display 
' the buttons in American English. 

Dim mbresult As Long ' result of message box 
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Dim flags As Long 
Dim lang As Long 





" For convenience, 


' message box flags 
language ID 











use a variable to represent the flag settings. 














flags = MB_YESNO Or MB_ICONWARNING Or MB_DEFBUTTON2 Or MB_SYSTEMMODAL 


' Generate the proper language ID. 























lang = MAKELANGID (LANG_ENGLISH, SUBLANG_ENGLISH_US) 

















' Display the message box. 
mbresult = MessageBox (Forml.hWnd, "Are you sure you want to do that?", 





flags, lang) 





' Determine what the user pressed. 

















Elseif mbresult = 





End If 





See Also 


If mbresult = IDYES Then 
Debug.Print "OK, go ahead and do that." 








IDNO Then 
Debug.Print "Operation aborted." 





MessageBox, MessageBoxIndirect 





Category 


Dialog Boxes 


Back to the Function list. 





Back to the Reference section. 


Last Modified: February 10, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/m/messageboxex.html 
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MessageBoxindirect Function 


Declare Function MessageBoxIndirect Lib "user32.dl1l" Alias "MessageBoxIndirectA" 
(lpMsgBoxParams As MSGBOXPARAMS) As Long 





Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 4.0 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


MessageBoxIndirect opens and operates a small message box on the screen. Message boxes are typically used either to 
communicate important information (such as an error message) or to prompt the user. This function offers more options 
for the creation of the message box than MessageBox and MessageBoxEx do because this function stores those options 








in a structure passed to the function. The message box only closes when the user presses one of the buttons presented. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one 
of the following flags specifying the button the user clicked on: 


IDABORT 
The Abort button was clicked. 
IDCANCEL 
The Cancel button was clicked (or the user dismissed the message box using the Esc key). 
IDCONTINUE 
Windows 2000: The Continue button was clicked. 
IDIGNORE 
The Ignore button was clicked. 
IDNO 
The No button was clicked. 
IDOK 
The OK button was clicked. 
IDRETRY 
The Retry button was clicked. 
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IDTRYAGAIN 

Windows 2000: The Try Again button was clicked. 
IDYES 

The Yes button was clicked. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpMsgBoxParams 
The settings used to create and operate the message box. 


Constant Definitions 


Const IDABORT = 3 
Const IDCANCEL = 2 
Const IDCONTINUE = 5 
Const IDIGNORE = 5 
Const IDNO = 7 

Const IDOK = 1 

Const IDRETRY = 4 
Const IDTRYAGAIN = 4 
Const IDYES = 6 








Example 


This code is licensed according to the terms and conditions listed here. 


Create a Yes/No dialog for the user. Also offer a Help 
button which opens the corresponding topic in a WinHelp file. 
The message box is owned by window Forml. Pay attention 

to where various parts of the example code must be placed. 








' **x* Place the following code in a module. *** 
' This callback function handles the message box's Help button. 
Public Sub MsgBoxCallback (lpHelpInfo As HELPINFO) 


Dim retval As Long ' return value 














Open the proper topic in the help file "C:\MyProg\proghelp.hip". 
The desired Context ID is found inside the structure. 

retval = WinHelp(Forml.hWnd, "C:\MyProg\proghelp.hlp", HELP_CONTEXT, 
lpHelpInfo.dwContextId) 
End Sub 
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' This is a dummy function, 


mere] 


ly returning what is passed to it. This 





Ang 


' is needed because the AddressOf operator is only valid inside 


a function call, whereas we need to use it to set a data member. 
Public Function DummyFunc (ByVal param As Long) As Long 
param 











DummyFunc 
End Function 


1 KkK*k 





xxx Place the following code where you want to create the message box. 
Dim mbp As MSGBOXPARAMS ' message box's parameters 





Dim mbresult As Long result of message box 


' Fill in the parameter structure for the message box. 


With mbp 
.cbSize Len (mbp) 
-hwndOwner = Forml.hWnd 


size of structure 
' window which owns the message box 
-hiInstance App.hInstance ' handle to instance of this program 
.lpszText = "Are you sure you want to do that?" ' message box text 
.lpszCaption "User Prompt" message box's title bar text 

.dwStyle MB_YESNO Or MB_HELP Or MB_ICONQUESTION ' flags for display 
.lpszicon 0 not needed 

.dwContextHelpId 2300 
. lpfnMsgBoxCallback DummyFunc (AddressOf MsgBoxCallback) 


Context ID for the proper topic in the Help file 
' pointer to calback 











function 
. dwLanguageld 


" use American 


= MAKELANGID (LANG_ENGLISH, SUBLANG_ENGLISH_US) 





English 
End With 


' Display the message box. 


mbresult MessageBoxIndirect (mbp) 

' Determine what the user pressed. 

If mbresult IDYES Then 

Debug.Print "OK, go ahead and do that." 
seif mbresult IDNO Then 

Debug.Print "Operation aborted." 

End If 








El 








See Also 


MessageBox, MessageBoxEx 





Category 


Dialog Boxes 


Back to the Function list. 
Back to the Reference section. 
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Last Modified: February 11, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/m/messageboxindirect.html 
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mouse event Function 








Declare Sub mouse_event Lib "user32.dll" (ByVal dwFlags As Long, ByVal dx As Long, 
ByVal dy As Long, ByVal cButtons As Long, ByVal dwExtraiInfo As Long) 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


mouse_event synthesizes mouse input by placing mouse input information into the input stream. A single mouse input 
event consists of either a move of the mouse or the change of the button state. For mouse movement, the coordinates can be 
given in either absolute or relative form. Only changes in mouse position or button state should be send via this function. 
For example, if the left mouse button is already down, the program should not send another left-button-down input. 


Return Value 


mouse_event does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwFlags 
A combination of the following flags specifying which mouse input information to place into the input stream. 
Remember to only specify button status information for those which have changed. Note that scroll wheel movement 
and X button status cannot be simultaneously specified because they both use the dwData parameter. 
MOUSEEVENTF_ABSOLUTE 
The dx and dy parameters contain absolute mouse coordinates. In the coordinate system used by the function, 
the screen's upper-left corner has coordinates (0,0) and the lower-right corner has coordinates (65535,65535), 
regardless of the actual screen size. If this flag is not set, dx and dy contain relative coordinates, whose actual 
amount of movement depends on the current mouse speed and acceleration settings. 
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dx 


dy 


MOUSEEVENTF_LEFTDOWN 
The left button was pressed. 
MOUSEEVENTF_LEFTUP 
The left button was released. 
MOUSEEVENTF_MIDDLEDOWN 
The middle button was pressed. 
MOUSEEVENTF_MIDDLEUP 
The middle button was released. 
MOUSEEVENTF_MOVE 
The mouse moved. The dx and dy parameters specify the amount or location of the movement. 
MOUSEEVENTF_RIGHTDOWN 
The right button was pressed. 
MOUSEEVENTF_RIGHTUP 
The right button was released. 
MOUSEEVENTF_WHEEL 
Windows NT, 2000: The scroll wheel has moved. The dwData parameter specifies the amount of movement. 
MOUSEEVENTF_XDOWN 
Windows 2000: An X button was pressed. The dwData parameter identifies which X buttons. 
MOUSEEVENTF_XUP 
Windows 2000: An X button was released. The dwData parameter identifies which X buttons. 





Specifies either the x-coordinate of absolute mouse movement or the amount of relative movement along the x-axis. 
For relative motion, positive values move right and negative values move left. 


Specifies either the y-coordinate of absolute mouse movement or the amount of relative movement along the y-axis. 
For relative motion, positive values move down and negative values move up. 


dwData 


Windows NT, 2000: If dwFlags contains MOUSEEVENTF_WHEEL, this specifies the amount of wheel 
movement, in integer multiples of WHEEL_DELTA. Positive values mean forward (away) rotation, and negative 
values mean backwards (toward) rotation. Windows 2000: If dwFlags contains either MOUSEEVENTF_XDOWN 
or MOUSEEVENTF_XUP, this is a combination of the following flags specifying which X buttons have been 
pressed or released: 
XBUTTONI1 

The first X button was pressed or released. 
XBUTTON2 

The second X button was pressed or released. 


dwExtralnfo 


An additional 32-bit value associated with the mouse event. 


Constant Definitions 


Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 





Con 
























































st MOUSEEVENTF_ABSOLUTE = &H8000 
st MOUSEEVENTF_LEFTDOWN = &H2 

st MOUSEEVENTF_LEFTUP = &H4 

st MOUSEEVENTF_MIDDLEDOWN = &H20 
st MOUSEEVENTF_MIDDLEUP = &H40 
st MOUSEEVENTF_MOVE = &H1 

st MOUSEEVENTF_RIGHTDOWN = &H8 
st MOUSEEVENTF_RIGHTUP = &H10 

st MOUSEEVENTF_WHEEL = &H80 
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Const 
Const 
Const 
Const 
Const 


MOUSEEVENTF_XDOWN = 
MOUSEEVENTF_XUP = 
WHEEL DELTA = 
XBUTTONI = 
XBUTTON2 = 


&H100 
&H200 








120 
&H1 
&H2 





Example 


Simulate clicking the left mouse button at the upper-left corner of the screen. Although we could use the mouse_event 
function to move the cursor, it is much easier to use SetCursorPos instead. The example runs when the user clicks button 
Command]. Obviously, to use this example, you must place a command button named Command! on a form window. 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 
section of a module.) 
dwFlags As Long, 


" (Copy 
Public 
Long, 


Public 


them to the (declarations) 





Declare Sub mouse_event Lib 
ByVal dy 


As Long, 








ByVal cButtons As Long, 
Declare Function SetCursorPos Lib 





"user32.dl] 


W 


(ByVal 








ByVal 


dwExtral 








"user32.dl11" 


(ByVal 








Long) As Long 


Private 


End Sub 


Sub Command1_Click () 
Dim retval As Long ' 








' Move the mouse cursor to the upper-left corner of the screen. 


retval = SetCursorPos(0, 0) 





return value 


' Click the left mouse button once. 





mouse_event MOUSEEVENTF_LEFTDOWN, 


0, O 





mouse_event MOUSEEVENTF_ LEFT 


See Also 


keybd_event, SendInput 


Category 


Mouse 


Go back to the Function listing. 
Go back to the Reference section index. 





Last Modified: August 26, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





UP, 0, 0, 


0, 
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0 


[nfo As Long) 


x As Long, 


ns and conditions listed here. 


ByVal dx As 


ByVal y As 


Windows API Guide: mouse_event Function 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/m/mouse_event.html 
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MoveFile Function 


Declare Function MoveFile Lib "kernel32.d1l1" Alias "MoveFileA" (ByVal 
lpExistingFileName As String, ByVal lpNewFileName As String) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


MoveFile moves or renames a file or directory -- it's really the same operation either way. If a directory is 
moved/renamed, all of the subdirectories and files contained in it will similarly be moved/renamed to reflect the 
path change. The function returns 1 if successful, or 0 if an error occured. 


[pExisting FileName 
The source file or directory; i.e., the file or directory to rename (move). 

lpNewFileName 
The target file or directory; i.e., the new file or directory name to give the source file (where to move the 
file or directory). 


Example: 





' Move the file to C:\MyFiles\temp.txt to C:\Dummy\buffer.txt. 

' The original file will no longer exist. Note how this example both changes 
' the filename and moves the file into a different directory simultaneously. 
Dim retval As Long ' 











return value 


retval = MoveFile("C:\MyFiles\temp.txt", "C:\Dummy\buffer.txt") 


See Also: CopyFile 
Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/m/movefile.html 
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MoveMemory Function 





Declare Sub MoveMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination As 
Any, Source As Any, ByVal Length As Long) 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


MoveMemory moves the contents of a portion of memory from one location to another. The two locations are identified 
by pointers to the memory addresses. After the copy, the original contents in the source are set to zeros. 


Return Value 


MoveMemory does not return a value. 


Visual Basic-Specific Issues 


A pointer to any variable can be automatically generated merely be passing that variable as either Destination or Source. 
However, if either a String or a Long holding the desired memory address is passed, the By Val keyword must preceed it. 


Parameters 


Destination 

A pointer to the memory address to use as the target, which receives the transfered data. 
Source 

A pointer to the memory address to use as the source, which initially holds the data to be transfered. 
Length 

The number of bytes of data to copy from the source memory location to the target memory location. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Transfer the contents of one byte array to another. After the transfer, 
" the contents of the source array are set to 0. 





Dim source(0 To 9) As Byte ' source array of 10 bytes 
Dim target(0 To 9) As Byte ' similarly sized target array 
Dim c As Integer ' counter variable 


' Fill the source array with some information. 





For c = 0 To 9 ' loop through each element 
source(c) = c ' set each element's value to its index 
Next c 


' Transfer the data from the target array to the source array. Note how pointers 
' are implied merely by passing the arrays as usual. 
MoveMemory target(0), source(0), 10 ' copy all 10 bytes 


' Verify that the contents were transfered. 
For c = 0 To 9 
Debug.Print target (c); ' this will now contain the information 


Next c 
See Also 
CopyMemory 


Category 


Memor 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





Last Modified: July 28, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/m/movememory.html 
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MoveToEx Function 











Declare Function MoveToEx Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal x As Long, ByVal 
y As Long, lpPoint As POINT TYPE) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


MoveToKEx sets the current point of a device. The current point is the starting point from which all graphics APIs ending with 
"To" (such as LineTo) begin drawing from. Some programming languages call this point the last point referenced. This 
function also puts the former current point into the variable passed as /pPoint. The function returns 0 if an error occured, or 1 if 
successful. 


hdc 

The device context of the device to set the current point of. 
x 

The x coordinate of the point to set as the current point. 
y 


The y coordinate of the point to set as the current point. 
[pPoint 
Variable that receives the coordinate of the former current point. 


Example: 





' Draw a red line from (0,40) to (100,50) on the window Forml. 
































Dim pt As POINT TYPE ' receives the former current point 

Dim retval As Long ' return value 

Forml.ForeColor = RGB(255, 0, 0) ' set the foreground drawing color of Forml to red 
retval = MoveToEx(Forml.hdc, 0, 40, pt) " set the current point to (0,40) 


' Note that pt now contains whatever the old current point was, but it doesn't matter 
here. 
retval = LineTo(Forml.hdc, 100, 50) ' draw a line from current point to (100,50) 





Category: Lines & Curves 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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MoveWindow Function 


Declare Function MoveWindow Lib "user32.dll" (ByVal hwnd As Long, ByVal x As 
Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
bRepaint As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


MoveWindow moves a window to a new location. In addition to moving it, this function also changes the window's 
size to a new width and height. The function returns 1 if successful, or 0 if an error occured. 


hwnd 
The handle of the window to move and resize. 


The x-coordinate to position the upper-left corner of the window at. 
y 
The y-coordinate to position the upper-left corner of the window at. 
nWidth 
The width in pixels to resize the window to. 
nHeight 
The height in pixels to resize the window to. 
bRepaint 
If 1, updates the screen to display the window at its new position. If 0, does not update the screen to reflect the 
move (the window will appear to be unmoved but will actually be at its new location!). 


Example: 
' Move window Forml. Set its upper-left corner to the point (200, 150). 


' Change its size to a width of 175 and a height of 300. 
Dim retval As Long ' return value 





' Move the window and make sure it's redrawn at its new position. 
retval = MoveWindow(Forml.hWnd, 200, 150, 175, 300, 1) 
' (If the last value had been 0, the window would have appeared to be unmoved!) 


See Also: GetWindowRect, SetWindowPos 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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MulDiv Function 


Declare Function MulDiv Lib "kernel32.d11" (ByVal nNumber As Long, ByVal 
nNumerator As Long, ByVal nDenominator As Long) As Long 


Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


MulDiv multiplies two 32-bit integers together and divides the resulting 64-bit integer by a 32-bit integer. The 
final result is (usually) a 32-bit integer. This function is useful because it can calculate expressions which, 
although resulting in a perfectly acceptable value, would otherwise cause an overflow error if the 

programming language's arithmetic operators were used. If the end result is not an integer, it is rounded to the 
nearest integer. 


Return Value 


If an error occured (such as if the result is greater than a 32-bit value or division by zero was attempted), the 
function returns -1. If successful, the function returns the result of the expression (1nNumber * nNumerator) / 
nDenominator rounded to the nearest integer. 


Visual Basic-Specific Issues 


None. 


Parameters 


nNumber 
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The first number to multiply. 
nNumerator 

The second number to multiply. 
nDenominator 

The number to divide by. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Demonstrate how MulDiv can help avoid producing overflow errors. 
Dim result As Long 








' Without MulDiv: If you uncomment the line below, an overflow error 
1 


will occur because the result of the multiplication is greater 
' than a 32-bit value. 
'result = -134217728 * 243 / 110592 


' With MulDiv: There is no problem calculating the result. 
result = MulDiv(-134217728, 243, 110592) 
' (The result is exactly -294912.) 


Category 
Math 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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OffsetRect Function 


Declare Function OffsetRect Lib "user32.d11" (lpRect As RECT, ByVal x As Long, 
ByVal y As Long) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


OffsetRect changes the position of a rectangle without changing its size. If the value to move by is negative, the rectangle is 
moved left or up (depending on the direction); positive values move it right or down. The function returns 0 if an error 
occured, or | if successful. 




















IpRect 
The rectangle to move. 
x 
The value to move the rectangle horizontally by. Negative values move to the left, positive to the right. 
y 
The value to move the rectangle vertically by. Negative values move up, positive down. 
Example: 
' Shift window Forml 50 pixels right and 20 pixels up using its rectangle. 
Dim winrect As RECT ' receives the rectangle of the window 
Dim retval As Long ' return value 
retval = GetWindowRect (Forml.hWnd, winrect) ' get Forml's rectangle 
retval = OffsetRect (winrect, 50, -20) ' shift the rectangle 50 to the right and 20 
upwards 
' Now change the window on screen to match its new rectangle 
retval = SetWindowPos(Forml.hWnd, 0, winrect.Left, winrect.Top, winrect.Right, 





winrect.Bottom, 0) 


See Also: InflateRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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OffsetRgn Function 


Declare Function OffsetRgn Lib "gdi32.d11" (ByVal hRgn As Long, ByVal x As Long, 
ByVal y As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


OffsetRgn translates (slides) a region by a specified amount horizontally and vertically. The region can be moved in any 
direction left, right, up, or down. The function returns 0 if an error occured, or exactly one of the following flags identifying 
the shape of the region which was moved: 


COMPLEXREGION = 3 

The region is not empty but is not a rectangle. 
NULLREGION = 1 

The region is empty, i.e., null. 
SIMPLEREGION = 2 

The region is rectangular in shape. 




















hRgn 
A handle to the region to move. 
x 
The number of pixels to move the region horizontally. Positive values move to the right; negative ones move to the 
left. 
y 
The number of pixels to move the region vertically. Positive values move down; negative ones move up. 
Example: 
' On window Forml, fill an elliptical region in light gray. Then translate the 
' region 50 pixels right and 20 pixels up and fill it with dark gray. 
Dim hRgn As Long ' handle to the region 
Dim hLightBrush As Long, hDarkBrush As Long ' handles to the two brushes to be used 
Dim retval As Long ' generic return value 











" Create the elliptical region. 

hRgn = CreateBRllipticRgn(20, 100, 220, 200) " bounding rectangle (20,100)-(220,200) 
' Get handles to the light and dark gray solid stock brushes. 

hLightBrush = GetStockOb ject (LTGRAY_BRUSH) 

hDarkBrush = GetStockObject (DKGRAY_BRUSH) 



































' Fill in the region in its current location on Forml in light gray. 
retval = FillRgn(Forml.hDC, hRgn, hLightBrush) 





Slide the region 50 pixels right and 20 pixels up. 
retval = OffsetRgn(hRgn, 50, -20) ' -20 means 20 up, not down 
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' Fill in the region in its new location in dark gray. 
retval = FillRgn(Forml.hDC, hRgn, hDarkBrush) 














' Delete the region to free up resources. 

















retval = DeleteObject (hRgn) 
Category: Regions 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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OpenPrinter Function 
Declare Function OpenPrinter Lib "winspool.drv" Alias "OpenPrinterA" (ByVal 

















pPrinterName As String, phPrinter As Long, pDefault As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


OpenPrinter opens a printer and obtains a handle to it. This handle can then be used by a number of printer API functions to 
reference the printer. After your program is finished using this handle, it should close the printer via ClosePrinter. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get the 


error code). 


Visual Basic-Specific Issues 


When passing zero for pDefault, the expression ByVal CLng(0) must be used. 


Parameters 


pPrinterName 
The name of the printer or print server to obtain a handle to. If this is an empty string, the function obtains a handle to 
the default print server. 

phPrinter 
Receives a handle to the newly opened printer. 

pDefault 
A PRINTER_DEFAULTS structure specifying some options for opening the printer. To use the default settings, pass 
zero for this parameter. 








Example 
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Display the Properties dialog box for the system's default printer. The dialog box is opened when the user clicks the button 


cmdProperties. To use the example, first place a command button named cmdProperties on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed 


' (Copy them to the (declarations) 








Public Type PRINTER INFO 1 

flags As Long 

pDescription As String 

pName As String 
pComment As String 

End Type 




















Public Declare Function EnumPrinters Lib 


for the example: 








flags As Long, _ 
ByVal name As String, 





As Long, 


pcbNeeded As Long, pcReturned As Long) 








ByVal Level As Long, 


Public Const PRINTER _ENUM_ DEFAULT = &H1 
Public Declare Function lstrcpy Lib "kernel32.d11" 























As Any, 


ByVal lpString2 As Any 





section of a module.) 





"winspool.drv" Alias "EnumPrintersA" 








pPrinterl 


As Long 


Alias "lstrcpyA" (ByVal 


Enum As Long, 








) As Long 


Public Declare Function lstrlen Lib "kernel32.d11" 


As Any) As Long 








Public Declare Function OpenPrinter Lib "winspool. 


pPrinterName 


As String, phPrinter As Long, p 


Alias "lstrlenA" (ByVal 





ByVal 


( 


ByVal 








cdBuf 








lpStringl 





























Public Declare Function PrinterProperties Lib 














ByVal hPrinter _ 
As Long) As Long 





Public Declare Function ClosePrinter Lib 








Long 


' *** Place the following code 





drv" 


Default As Any) 
"winspool.drv" (ByVal hWnd As Long, 





inside a form window. *** 


Private Sub cmdProperties_Click () 

















im slength As Long 
im hPrinter As Long 
im retval As Long 























' Figure out how much space is n 
retval = EnumPrinters (PRINT 











bytesNeeded, numPrinters) 





Alias 


lpString 











As Long 



































E 


' length of 


' handle to the printer 
' generic return value 


























eeded to store 
ER_ENUM_DEFAULT, 





the printer in 


string to copy 











vbNullString, 1, ByVal 0, 


' Allocate that much space in the buffer array. 
ReDim buffer(0 To bytesNeeded / 4 - 1) As Long 
' Get information about the default printer. 

















retval = EnumPrinters (PRINTER_ENUM_DEFAULT, 
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0, 


vbNullString, 1, buffer (0), 





"OpenPrinterA" (ByVal 


"winspool.drv" (ByVal hPrinter As Long) As 


Dim pil As PRINTER INFO 1 ' a little info about the printer 

im bytesNeeded As Long ' size needed for buffer 

im numPrinters As Long ' number of printers enumerated (should be 1) 
im buffer () As Long ' buffer for printer information 


Windows API Guide: OpenPrinter Function 


bytesNeeded, 
bytesNeeded, numPrinters) 
' Make sure we were successful. 
If retval = 0 Or numPrinters <> 1 Then 
Debug.Print "No default printer or some other error." 
Exit Sub 











End If 








' Copy the data into the structure. 
With pil 
' Copy numerical data directly. 
.flags = buffer (0) 
' Strings require more work, since the buffer holds pointers to them. 






































-pDescription = Space (lstrlen (buffer (1))) 
retval = lstrcpy(.pDescription, buffer (1)) 
.pName = Space (lstrlen (buffer (2))) 

retval = lstrcpy(.pName, buffer (2)) 
.pComment = Space (lstrlen (buffer (3))) 
retval = lstre (.pComment, buffer (3)) 














End With 





' Open the printer. 
retval = OpenPrinter(pil.pName, hPrinter, ByVal CLng(0)) 
If retval <> 0 Then 

' Display the properties dialog. 



































retval = PrinterProperties(Me.hWnd, hPrinter) 
' Close the printer. 
retval = ClosePrinter (hPrinter) 
Else 
Debug.Print "Unable to open printer!" 
End If 


End Sub 





See Also 


ClosePrinter 


Category 


Printers 


Go back to the Function listing. 
Go back to the Reference section index. 
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PicklconDlg Function 


Declare Function PickIconDlg Lib "Shel132.d11" Alias "#62" (ByVal hwndOwner As Long, 
ByVal lpstrFile As String, ByVal nMaxFile As Long, lpdwIconIndex As Long) As Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Unknown. 


PickIconDlg is officially undocumented. 


Description & Usage 


PickIconDlg displays the standard Windows "icon selection" dialog box. It allows the user to choose an icon found inside a 
file. The function then reports which icon the user selected, if any. 


Windows NT, 2000: All strings used by this function must be Unicode. Therefore, any strings passed to the function must first 
be converted into Unicode. Likewise, any strings output by the function also must be converted from Unicode into ANSI. 


Return Value 


If successful, the function returns a non-zero value. If an error occured or the user did not choose an icon (for example, the user 
clicked "Cancel"), the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


hwndOwner 
A handle to the window which is opening the icon selection dialog box. 

IpstrFile 
A null-terminated string specifying the default icon-containing file to look inside. This string will also receive the name 
of the file which holds the user's selection. Therefore, this string must have enough empty space after the terminating 
null character to receive the final string. 
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nMaxFile 


The length of the string passed as IpstrFile. 
lpdwIconIndex 
The zero-based index of the icon to select by default. This variable also receives the zero-based index of the icon the 
user selected. 


Example 


' This code is licensed according to the terms and conditions listed here. 









































































































































































































































' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function PickIconDlg Lib "shell132.d11" Alias "#62" (ByVal hwndOwner As 
Long, 

ByVal lpstrFile As String, ByVal nMaxFile As Long, lpdwIconIndex As Long) As 
Long 
Public Type OSVERSTIONINFO 

dwOSVersioniInfoSize As Long 

dwMajorVersion As Long 

dwMinorVersion As Long 

dwBuildNumber As Long 

dwPlatformiId As Long 

szCSDVersion As String * 128 
End Type 
Public Const VER_PLATFORM WIN32_NT = 2 
Public Const VER_PLATFORM_WIN32 WINDOWS = 1 
Public Declare Function GetVersionEx Lib "kernel32.d1l1" Alias "GetVersionExA" _ 

(lpVersionInformation As OSVERSIONINFO) As Long 
Public Declare Function ExtractIcon Lib "shel132.d11" Alias "ExtractIconA" (ByVal 
hinst _ 

As Long, ByVal lpszExeFileName As String, ByVal nIconIndex As Long) As Long 
Public Declare Function Drawlcon Lib "user32.dl1" (ByVal hDC As Long, ByVal x As 
Long, 

ByVal y As Long, ByVal hIcon As Long) As Long 
Public Declare Function DestroylIcon Lib "user32.dll1" (ByVal hIcon As Long) As Long 
Public Declare Function GetSystemDirectory Lib "kernel32.dll1" Alias 
"GetSystemDirectoryA" _ 

(ByVal lpBuffer As String, ByVal nSize As Long) As Long 
' When the user presses button Commandl, display an icon selection dialog box. If 
the 
' user chooses an icon, then draw it in the corner of window Forml's client area. 
Private Sub Command1_Click () 

Dim iconfile As String ' file that contains the desired icon 

Dim iconindex As Long ' index of the desired icon 

Dim slength As Long ' length of returned string 

Dim hIcon As Long ' handle to the icon once it is extracted 

Dim ovi As OSVERSTIONINFO ' identifies the Windows platform 

Dim retval As Long ' return value 

















' First, 


determine if the computer is running Windows NT or 2000. 
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case, 





' all strings used with PickIconDlg must be converted into Unicode. 
ovi.dwOSVersionInfoSize = Len (ovi) 
retval = GetVersionEx (ovi) 








Figure out where the System directory is. 
iconfile = Space (256) 
slength = GetSystemDirectory(iconfile, Len(iconfile) ) 

















iconfile = Left (iconfile, slength) 








' Have the default selection be the third icon in pifmgr.dll. Include plenty 
' of extra space in the string so it can receive the user's selection. 
iconfile = iconfile & "\pifmgr.d11" & vbNullChar & Space (256) 

iconindex = 2 














' Display the icon selection dialog. If Windows NT or 2000 is running, 
convert 








' the string to and from Unicode immediately before and after calling the 
function. 

If ovi.dwPlatformId = VER PLATFORM WIN32_NT Then 
iconfile = StrConv(iconfile, vbUnicode) 











End If 
retval = PickIconDlg(Forml.hWnd, iconfile, Len(iconfile), iconindex) 
If ovi.dwPlatformId = VER PLATFORM _WIN32_NT Then 

iconfile = StrConv(iconfile, vbFromUnicode) 





























End If 
' Remove the terminating null and empty space from the string. 


iconfile = Left(iconfile, InStr(iconfile, vbNullChar) - 1) 


























' If the user selected something, draw the icon on Forml. 
If retval <> 0 Then 
' Extract the icon from the file. 
hIcon = ExtractIcon(App.hInstance, iconfile, iconindex) 











' Draw it in the corner of the window. 
retval = DrawlIcon(Forml.hDC, 0, 0, hIcon) 














' Destroy the icon to free resources. 
retval = DestroylIcon (hIcon) 

















End Sub 





Category 
Shell 


Back to the Function list. 
Back to the Reference section. 





Last Modified: June 4, 2000 
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Pie Function 


Declare Function Pie Lib "gdi32.d11" (ByVal hdc As Long, ByVal X1 As Long, ByVal Y1 
As Long, ByVal X2 As Long, ByVal Y2 As Long, ByVal X3 As Long, ByVal Y3 As Long, 
ByVal X4 As Long, ByVal Y4 As Long) As Long 



































Platforms: Win 32s, Win 95/98, Win NT 


Pie draws an elliptical pie wedge on a device. The pie wedge is drawn using the device's currently selected pen and is filled 
using its currently selected brush. The pie wedge consists of two radials from the ellipse's center to the ellipse's edge, filling the 
area between them (going counterclockwise around the ellipse). The first two sets of (x,y) coordinate pairs specify the 
bounding rectangle which determines the ellipse. The last two sets of (x,y) pairs determine the points along the ellipse; the start 
and endpoints are determined by the intersection of a ray from the ellipse's center through the (x,y) coordinate and the ellipse. 
The function returns 1 if successful, or 0 if an error occured. 











hdc 
A device context to the device to draw the chord on. 
XI 
The x-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
Yl 
The y-coordinate of the upper-left corner of the ellipse's bounding rectangle. 
X2 
The x-coordinate of the lower-right corner of the ellipse's bounding rectangle. 
Y2 
The y-coordinate of the lower-right corner of the ellipse's bounding rectangle. 
X3 
The x-coordinate of the point determining the starting point of the pie wedge. 
Y3 
The y-coordinate of the point determining the starting point of the pie wedge. 
X4 
The x-coordinate of the point determining the ending point of the pie wedge. 
Y4 
The y-coordinate of the point determining the ending point of the pie wedge. 
Example: 
' Draw a pie wedge on window Forml. The ellipse has a bounding rectangle 
' of (10,20)-(210,120). The pie wedge will have endpoints on the ellipse of (210,70) 
' and (110,20) -- i.e., the "upper-right" fourth of the ellipse. Draw the pie wedge 
' using Forml's current brush and pen. 
Dim retval As Long ' return value 











' Draw the chord as specified above. 
retval = Pie(Forml.hDC, 10, 20, 210, 120, 210, 70, 110, 20) 
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See Also: Chord, Ellipse 
Category: Filled Shapes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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PlaySound Function 





Declare Function PlaySound Lib "winmm.dll" Alias "PlaySoundA" (ByVal lpszName As 
String, ByVal hModule As Long, ByVal dwFlags As Long) As Long 








Alternate Declare for when using a resource or memory location: 
Declare Function PlaySound_Res Lib "winmm.dll" Alias "PlaySoundA" (ByVal lpszName As 
Long, ByVal hModule As Long, ByVal dwFlags As Long) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


PlaySound plays a waveform sound through the speakers. This sound could be a .wav file, a system event sound (such as the 
system startup sound), or a sound resource stored in an application. Note that when the function needs to play an application 
resource or a RAM-loaded sound, Visual Basic users must use the alternate declare of the function in order to pass the 
numeric identifier of the sound instead of a string. The function returns 0 if an error occured, or a non-zero value if 
successful. 


IpszName 
The name or some other identifier of the sound. Its exact format depends on the flags passed as dwFlags. 

hModule 
A handle to the application module containing the sound resource the play, if needed. If the function does not need 
this information, pass 0 for this parameter. 

dwFlags 
Zero or more of the following flags specifying what /pszName refers to and how to play the sound: 
SND_ALIAS = &H10000 

IpszName is a string identifying the name of the system event sound to play. 

SND_ALIAS_ID = &H110000 

IpszName is a string identifying the name of the predefined sound identifier to play. 

SND_APPLICATION = &H80 

IpszName is a string identifying the application-specific event association sound to play. 

SND_ASYNC = &H1 
Play the sound asynchronously -- return immediately after beginning to play the sound and have it play in the 
background. 

SND_FILENAME = &H20000 
IpszName is a string identifying the filename of the .wav file to play. 

SND_LOOP = &H8 
Continue looping the sound until this function is called again ordering the looped playback to stop. 
SND_ASYNC must also be specified. 

SND_MEMORY = &H4 
IpszName is a numeric pointer refering to the memory address of the image of the waveform sound loaded into 
RAM. 

SND_NODEFAULT = &H2 
If the specified sound cannot be found, terminate the function with failure instead of playing the SystemDefault 
sound. If this flag is not specified, the SystemDefault sound will play if the specified sound cannot be located 
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and the function will return with success. 
SND_NOSTOP = &H10 
If a sound is already playing, do not prematurely stop that sound from playing and instead return with failure. 
If this flag is not specified, the playing sound will be terminated and the sound specified by the function will 
play instead. 
SND_NOWAIT = &H2000 
If a sound is already playing, do not wait for the currently playing sound to stop and instead return with failure. 
SND_PURGE = &H40 
Stop playback of any waveform sound. /pszName must be an empty string. 
SND_RESOURCE = &H4004 
IpszName is the numeric resource identifier of the sound stored in an application. hModule must be specified as 
that application's module handle. 
SND_SYNC = &HO 
Play the sound synchronously -- do not return until the sound has finished playing. 


Example: 
' First play the SystemStart event sound synchronously. Then loop 


' playing the file C:\Sounds\scream.wav for 5 seconds before stopping. 
Dim retval As Long ' return value of the function 














' Synchronously play the SystemStart sound. This function returns when the sound is 
done. 
retval = PlaySound("SystemStart", 0, SND_ALIAS Or SND_SYNC) 





' Now loop the .wav file for five seconds before purging its playback. Note that 
' we don't want the default sound to play if the file is not found. 

retval = PlaySound("C:\Sounds\scream.wav", 0, SND_FILENAME Or SND_ASYNC Or 
SND_NODEFAULT Or SND_LOOP) 





























Sleep 5000 ' wait for 5 seconds while sound loops 
retval = PlaySound("", 0, SND_PURGE Or SND_NODEFAULT) ' stop playback 





See Also: sndPlaySound 
Category: Audio 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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PolyBezier Function 


Declare Function PolyBezier Lib "gdi32.d11" (ByVal hdc As Long, lppt As 
POINT TYPE, ByVal cPoints As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


PolyBezier draws a series of cubic Bézier curves on a device. Each Bézier curve is drawn using the device's 
current pen. The function begins drawing the curves at a start point and draws each subsequent curve starting 


at the point where the previous one ended (for example, if the second curve ended at (100,50), the third curve 
would begin at (100,50) as well). 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a non-zero value. 


Visual Basic-Specific Issues 
None. 


Parameters 


hdc 
A handle to a device context to the device to draw the Bézier curves on. 
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ppt 


An array containing all the end points and control points for the Bézier curves. The first point is the 
starting point for the first curve. Each set of three points following the first identifies how to draw each 
curve: the first two points in the set are the two control points, and the third point is the end point of the 


curve. 
cPoints 


The number of elements in the array passed as /ppt. This value will have to be one more than three 


times the number of curves to draw. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Draw two Bézier curves on window Forml using the 








" solid black stock pen. The coordinates of the curves appear in 
" the example code. 

Dim hPen As Long ' handle to the solid black stock pen 

Dim hOldPen As Long ' handle to Forml's previous pen 

Dim pts(0 To 6) As POINT TYPE ' array of points for the curves 
Dim retval As Long ' return value 


' Load the seven points defining the two Bézier curves 








' into the array. The first four points define the first curve. 
pts (0).x = 100: pts(0).y = 100 ' lst curve starts at (100,100) 
pts (1).x = 125: pts(1).y = 75 ' control point (125,75) 
pts(2).x = 150: pts(2).y = 125 ' control point (150,125) 
pts(3).x = 175: pts(3).y = 100 ' Ist curve ends at (175,100) 

' The next three define the second curve, starting at (175,100) 
pts(4).x = 225: pts(4).y = 50 ' control point (225,50) 

pts (5).x = 300: pts(5).y = 150 ' control point (300, 150) 
pts(6).x = 250: pts(6).y = 200 ' 2nd curve ends at (250,200) 


' Get a handle to the solid black stock pen. 


hPen = GetStockObject (BLACK_PEN) 

' Select the pen for use in Forml. 
hOldPen = SelectObject (Forml.hDC, hPen) 

' Draw the two Bézier curves. 

retval = PolyBezier(Forml.hDC, pts(0), 7) 
' Select the previous pen used by Forml. 
retval = SelectObject (Forml.hDC, hOldPen) 











See Also 
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PolyBezierTo 





Category 


Lines & Curves 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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PolyBezierTo Function 


Declare Function PolyBezierTo Lib "gdi32.d11l" (ByVal hdc As Long, lppt As 
POINT TYPE, ByVal cCount As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


PolyBezierTo draws a series of cubic Bézier curves on a device. Each Bézier curve is drawn using the 
device's current pen. The function begins drawing the curves at the device's current point and draws each 


subsequent curve starting at the point where the previous one ended (for example, if the second curve ended at 
(100,50), the third curve would begin at (100,50) as well). 


Return Value 


If an error occured, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If 
successful, the function returns a non-zero value. 


Visual Basic-Specific Issues 
None. 


Parameters 


hdc 
A handle to a device context to the device to draw the Bézier curves on. 


http://216.26.168.92/vbapi/ref/p/polybezierto.html (1 of 3) [9/1/2002 5:37:33 PM] 


Windows API Guide: PolyBezierTo Function 


ppt 
An array containing all the end points and control points for the Bézier curves. Each set of three points 
identifies one curve: the first two points are the control points, and the third point is the end point of the 
curve. 

cPoints 


The number of elements in the array passed as /ppt. This value will have to be three times the number 
of curves to draw. 


Example 


' This code is licensed according to the terms and conditions listed here. 


" Use the solid black stock pen to draw a straight line, 

' followed by two Bézier curves on window Forml. The 

" coordinates of the line and curves appear in the example code. 
Dim hPen As Long ' handle to the solid black stock pen 

Dim hOldPen As Long ' handle to Forml's previous pen 

Dim curpt As POINT TYPE ' receives previous current point 

Dim pts(0 To 5) As POINT TYPE ' array of points for the curves 


Dim retval As Long ' return value 




















' Get a handle to the solid black stock pen. 
hPen = GetStockOb ject (BLACK_PEN) 

' Select the pen for use in Forml. 

hOldPen = SelectObject (Form1l.hDC, hPen) 








' Move the current point to (200, 25) and draw a line 
' to the point (100,100). 
retval = MoveToEx(Forml.hDC, 200, 25, curpt) 
retval = LineTo(Forml.hDC, 100, 100) 











' Load the six points defining the two Bézier curves 

















' into the array. The first three points define the first curve. 
' The curve will of course start of (100,100). 

pts (0).x = 125: pts(0).y = 75 ' control point (125,75) 

pts (1).x = 150: pts(1).y = 125 ' control point (150,125) 
pts(2).x = 175: pts(2).y = 100 ' lst curve ends at (175,100) 

' The next three define the second curve, starting at (175,100) 
PES (3).x = 225: pts(3).y = 50 ' control point (225,50) 

pts(4).x = 300: pts(4).y = 150 ' control point (300, 150) 
pts(5).x = 250: pts(5).y = 200 ' 2nd curve ends at (250,200) 


' Draw the two Bézier curves. 
retval = PolyBezierTo(Forml.hDC, pts(0), 6) 


http://216.26.168.92/vbapi/ref/p/polybezierto.html (2 of 3) [9/1/2002 5:37:33 PM] 


Windows API Guide: PolyBezierTo Function 


' Select the previous pen used by Forml. 
retval = SelectObject (Forml.hDC, hOldPen) 





See Also 


PolyBezier 


Category 


Lines & Curves 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: November 11, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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Polygon Function 


Declare Function Polygon Lib "gdi32.d1l1" (ByVal hdc As Long, lpPoint As 
POINT TYPE, ByVal nCount As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


Polygon draws and fills a polygon on a device. The polygon is drawn using the current pen and is filled using the 
current brush. The vertices of the polygon are stored in an array passed as /pPoint, in sequential order. Only specify 
each point once. The function returns 1 if successful, or 0 if an error occured. 


hdc 
A device context to the device to draw the polygon on. 
IpPoint 
An array holding the vertices of the polygon in the order which they will be drawn in. Specify each point 
only once. 
nCount 
The number of elements in the array passed as [pPoint. 
Example: 


iJ 


Draw a diamond on window Forml using the default pen and 
' brush. Note how the points must be loaded into the array before calling the 
function. 

















Dim points(0 To 3) As POINT TYPE ' vertices of the polygon 

Dim retval As Long ' return value 

' Load the coordinates of the diamond's vertices into the array. 
points (0).x = 200: points(0).y = 100 ' 1st point a 
points (1).x = 250: points(1).y = 150 ' 2nd point (250,150) 
points (2).x = 200: points(2).y = 200 ' 3rd point (200, a 
points (3).x = 150: points(3).y = 150 ' 4th point (150,150) 


iJ 


Draw the diamond using Forml's default pen and brush 
retval = Polygon(Forml.hDC, points(0), 4) ' four points in the array 





See Also: PolyPolygon 
Category: Filled Shapes 





Go back to the alphabetical Function listing. 
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Go back to the Reference section index. 
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Polyline Function 





Cl 


` 


Declare Function Polyline Lib "gdi32.dll1" (ByVal hdc As Long, lpPoint As POINT TYP] 
ByVal nCount As Long) As Long 











Platforms: Win 32s, Win 95/98, Win NT 


Polyline draws a series of lines on a graphics-capable device. These lines connect the points given in an array passed as 
[pPoint. Lines are drawn connecting the first point to the second point, the second point to the third point, etc. The first and last 
points are not connected. The lines are drawn using the device's current drawing color. The function returns 1 if successful, or 
O if an error occured. 


hdc 

The device context of the device to draw the lines on. 
[pPoint 

An array specifying the x and y coordinates of each point to draw lines to or from. 
nCount 

The number of elements in the array passed as /pPoint. 


Example: 








' Draw a triangle having corners (100,100), (200, 150), and (0, 150) 

















' on window Forml. Note how since we want the first and last points to be connected, 
' point (100,100) must be given as both the first and last points. 

Dim points(0 To 3) As POINT API ' the points to draw to/from 

Dim retval As Long ' return value 

' Put the points to use into the array. Four points must be specified to draw the 








' triangle because the point (100,100) must be entered twice. 



































( 
points(0).x 100: points(0).y = 100 ' point #0: (100,100) 
points(1).x = 200: points(1).y = 150 ' point #1: (200,150) 
points(2).x = 0: points(2).y = 150 ' point #2: (0,150) 
points(3).x = 100: points(3).y = 100 ' point #3: (100,100) 
Forml.ForeColor = RGB(255, 0, 0) ' set Forml's drawing color to red 
retval = Polyline(Forml.hDC, points(0), 4) ' draw the lines 





See Also: LineTo, PolylineTo, PolyPolyline 
Category: Lines & Curves 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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PolylineTo Function 





Declare Function PolylineTo Lib "gdi32.dl1" (ByVal hdc As Long, lppt As 
POINT TYPE, ByVal cCount As Long) As Long 











Platforms: Win 32s, Win 95/98, Win NT 


PolylineTo draws a series of connected lines on a graphics-capable device. The points are given to the function inside an 
array passed as /ppt. The function draws lines connecting the device's current point to the first point, the first point to the 
second point, the second point to the third point, etc. When the function is finished, it sets the current point to whatever the 
last point in the array is. The original current point and the last point are not connected. The lines are drawn in the device's 
current drawing color. The function returns 1 if successful, or 0 if an error occured. 


hdc 

The device context of the device to draw the lines on. 
lppt 

An array of points to connect using the lines. 
cCount 

The number of elements in ppt. 


Example: 





' Draw a red triangle with corners (100,100), (200,150), and (0,150) 

' on window Forml. The current point must first be set to (100,100), and the last 
' point must also be given as (100,100) to close the triangle. 

Dim points(0 To 2) As POINT TYPE ' points given to the function 














Dim curpt As POINT TYPE ' receives current point from MoveToEx 








Dim retval As Long ' return value 





' Set Forml's current point to (100,100) 
retval = MoveToEx(Forml.hDC, 100, 100, curpt) 








' Load the points of the triangle into the array points(). Notice that (100,100) 
' is given as the last point to close the figure. 

points(0).x = 200: points(0).y = 150 ' point #0: (200,150) 

points(1).x = 0: points(1).y = 150 ' point #1: (0,150) 
points(2).x = 100: points(2).y = 100 ' point #2: (100,100) 




















Forml.ForeColor = RGB(255, 0, 0) ' set Forml's drawing color to red 
retval = PolylineTo(Forml.hDC, points(0), 3) ' draw the lines 





See Also: LineTo, Polyline, PolyPolyline 
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Category: Lines & Curves 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 
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PolyPolygon Function 


Declare Function PolyPolygon Lib "gdi32.d11" (ByVal hdc As Long, lpPoint As 
POINT TYPE, lpPolyCounts As Long, ByVal nCount As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


PolyPolygon draws multiple polygons on a given device. The polygons are drawn using the device's current pen and are 
filled using the device's current brush. The various polygons are not connected. The vertices of every polygon are stored 
in an array passed as /pPoint. The array passed as /[pPolyCounts identifies the number of vertices in each polygon. This 
function is equivalent to calling the Polygon function multiple times. The function returns 1 if successful, or 0 if an error 
occured. 


hdc 
A device context to the device to draw the polygons on. 

[pPoint 
An array holding all of the vertices of every polygon to draw, listed in their proper order. Do not specify any point 
more than once in each polygon's set of vertices. 

IpPolyCounts 
An array holding the number of points in /pPoint belonging to each polygon. For example, /pPolyCounts(0) 
identifies the number of points belonging to the first polygon, etc. 

nCount 
The number of elements in the array passed as /pPolyCounts. 


Example: 


' Draw a diamond and a triangle on window Forml. The two 
' polygons are not interconnected and are drawn using the window's current pen 


' and brush. Note how the two arrays delineate each polygon's set of vertices. 











Dim points(0 To 6) As POINT TYPE ' holds diamond's and triangle's vertices 
Dim numpoints(0 To 1) As Long ' holds number of points belonging to each polygon 
Dim retval As Long ' return value 

' Load the points belonging to the diamond. 

points(0).x = 200: points(0).y = 100 ' Ist point: (200,100) 

points(1).x = 250: points(1).y = 150 ' 2nd point: (250,150) 

points(2).x = 200: points(2). : = 200 ' 3rd point: (200,200) 

points(3).x = 150: points(3).y = 150 ' 4th point: (150,150) 

numpoints(0) = 4 ' first Ce points identify the diamond 

' Load the points belonging to the triangle. 

points (4).x = 350: points(4).y = 200 ' Ist point: (350,200) 
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points(5).x = 400: points(5).y = 250 ' 2nd point: (400,250) 
points(6).x = 300: points(6).y = 250 ' 3rd point: (300,250) 
numpoints(1) = 3 ' next three points identify the triangle 


' Draw the two polygons 
retval = PolyPolygon(Forml.hDC, points(0), numpoints(0), 2) ' two polygons 


See Also: Polygon 
Category: Filled Shapes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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PolyPolyline Function 





Cl 


` 





Declare Function PolyPolyline Lib "gdi32.d11" (ByVal hdc As Long, lppt As POINT TYP] 
lpdwPolyPoints As Long, ByVal cCount As Long) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


PolyPolyline draws multiple sets of lines connecting points on a graphics-capable device. This function has a similar effect as 
using Polyline with various sets of points. Lines are drawn to connect the first point in a set to the second point, the second 
point to the third, etc. The first and last points in a set are not connected, just as the sets are not connected to each other. All of 
the points go into an array passed as /ppt. The connecting lines are drawn in the object's current drawing color. The function 
returns 1 if successful, or 0 if an error occured. 


























hdc 
The device context of the device to draw the lines on. 
ppt 
An array holding all of the points in every set. This should have all of the points in the first set, followed by those in the 
second set, followed by those in the third set, etc. 
lpdwPolyPoints 
An array identifying how many points belong to each set. The first element specified how many points are in the first 
set, etc. 
cCount 
The number of elements in lpdwPolyPoints. 
Example: 
' Draw a red triangle and a red parallelogram on window Forml. The 
' triangle has corners (100,100), (200,150), and (0,150). The parallelogram has 
corners 
" (300,300), (400,300), (350,400), and (250,400). Note that since the first and last 
points 
' are not connected, the beginning point is also specified as the last point in order 


" to close the figures. 
Dim points(0 To 8) As POINT TYPE ' the points in both sets 
' the number of points in each set 








Dim numpoints(0 To 1) As Long 
Dim retval As Long ' return value 











' Load the points for the triangle into the array. The point (100,100) is both the 























first 

' and last points in order to close the figure. 

points (0).x 100: points(0).y = 100 ' point #0: (100,100) 
points(1).x = 200: points(1).y = 150 ' point #1: (200,150) 
points (2).x = 0: points(2).y = 150 ' point #2: (0,150) 
points (3).x = 100: points(3).y = 100 ' point #3: (100,100) 
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numpoints(0) = 4 ' number of points in first set 





' Load the points for the parallelogram in a similar fashion. 




















points(4).x = 300: points(4).y = 300 ' point #4: (300,300) 

points(5).x = 400: points(5).y = 300 ' point #5: (400,300) 

points(6).x = 350: points(6).y = 400 ' point #6: (350,400) 

points(7).x = 250: points(7).y = 400 ' point #7: (250,400) 

points(8).x = 300: points(8).y = 300 ' point #8: (300,300) 

numpoints (1) = 5 ' number of points in second set 

' Now, finally draw both sets of points. The two are not mutually connected. 
Forml.ForeColor = RGB(255, 0, 0) ' set Forml's drawing color to red 

retval = PolyPolyline(Forml.hDC, points(0), numpoints(0), 2) ' draw the lines 


See Also: LineTo, Polyline, PolylineTo 





Category: Lines & Curves 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/p/polypolyline.html 
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PrintDlg Function 





Declare Function PrintDlg Lib "comdlg32.dl1" Alias "PrintDIgA" (pPrintdlg As 
PRINTDLG TYPE) As Long 

















Platforms: Win 32s, Win 95/98, Win NT 


PrintDlg displays either the Print common dialog box or the Print Setup dialog box. Either box can be used to allow the user to 
select a printer and other settings, such as the number of copies and the page range, desired for a print operation. Information 
for initializing the dialog box as well as information returned from it is stored in the structure passed as pPrintdlg. See the 
pages for the PRINTDLG_ TYPE, DEVMODE, and DEVNAMES structures for more details about using this function. Note 
that instead of using the latter two structures explicitly, handles to the memory blocks holding their data are required by the 
function; see the example below. The function returns 0 if either an error occured or the user pressed Cancel, or a non-zero 
value if the user successfully pressed OK. 


pPrintdlg 
Stores both the dialog box's initialization settings and the information returned from the dialog box. 


Example: 


' Open a Print common dialog box. Then display certain selections the user made, 
' such as the printer name, number of copies, and orientation. Carefully note how 
memory 

' blocks are allocated to hold the two data structures containing information about 


the 














' printer device. To save space, Visual Basic's Printer object, referring to the 
default 

' printer, is used to provide the defaults. Of course, API functions could also be 
used 








' to get these defaults. 











































































































Dim pd As PRINTDLG TYPE ' holds information to make the dialog box 

Dim printmode As DEVMODE ' holds settings for the printer device 

Dim printnames As DEVNAMES ' holds device, driver, and port names 

Dim pMode As Long, pNames As Long ' pointers to the memory blocks for the two DEV* 
structures 

Dim retval As Long ' return value of function 

' First, load default settings into printmode. Note that we only fill relevant 
information. 

printmode.dmDeviceName = Printer.DeviceNam ' name of the printer 

printmode.dmSize = Len(printmode) ' size of the data structure 

printmode.dmFields = DM_ORIENTATION ' identify which other members have information 
printmode.dmOrientation = DMORIENT_PORTRAIT ' default to Portrait orientation 
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' Next, load strings for default printer into printnames. Note the unusual way in 
which such 

' information is stored. This is explained on the DEVNAMES page. 
devnames.wDriverOffset = ' offset of driver name string 

devnames.wDeviceOffset devnames.wDriverOffset + + Len (Printer.DriverName) ' 
offset of printer name string 

devnames.wOutputOffset devnames.wDeviceOffset + + Len (Printer.Port) ' offset to 
output port string 

devnames.wDefault = 0 ' maybe this isn't the default selected printer 

' Load the three strings into the buffer, separated by null characters. 
devnames.extra = Printer.DriverName & vbNullChar & Printer.DeviceName & vbNullChar & 
Printer.Port & vbNullChar 

' Finally, load the initialization settings into pd, which is passed to the function. 
We'll 





" set the pointers to the 
pd.1lStructSize Len (pd) 
pd.hwndOwner Forml.hWnd 


structures after this. 
' size of structure 











' window Forml is opening the Print dialog box 









































' Flags: All Pages default, disable Print to File option, return device context: 
pd.flags = PD_ALLPAGES Or PD_DISABLEPRINTTOFILE Or PD_RETURNDC 

pd.nMinPage = ' allow user to select first page of "document" 

pd.nMaxPage = 15 ' let's say there are 15 pages of the "document" 





" Note how we 


' Copy the data in printmode and printnames into 
GlobalAlloc (GMEM_MOV 


pd.hDevMode 























can ignore those members which will 























be set or are not used here. 


the memory blocks we allocate. 








BLE 





EA 








Or GMEM_Z 








EROINIT, 














Len (printmode) ' allocate 


























memory block 

pMode = Globallock (pd.hDevMode) ' get a pointer to the block 

CopyMemory ByVal pMode, printmode, Len(printmode) ' copy structure to memory block 
retval = GlobalUnlock (pd. hDevMode) ' unlock the block 

" Now do the same for printnames. 

pd.hDevNames = GlobalAlloc (GMEM_MOVEABLE Or GMEM_ZEROINIT, Len (printnames) ' 
allocate memory block 

pNames = GlobalLock (pd.hDevNames) ' get a pointer to the block 








CopyMemory ByVal pNames, 


block 
retval 





' Finally, 
retval PrintDlg (pd) i 








S OE 
If 





retval <> 0 Then 
' First, 
almost identical 





' to the code above where we did the reverse. 


brevity. 


printnames, 


GlobalUnlock (pd.ħDevNames) ' 





pMode 


CopyMemory printmode, 
retval 


GlobalLock (pd.h 








pNames 





Len (printnames 





open the dialog box! 
looks so simple, 


doesn't i 





the user hit OK, display some information abou 


DevMode) 
ByVal pMode, 
GlobalUnlock (pd.hħhDevMode) 
GlobalLock (pd.hDevNames) 


Len (printmode) 
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) 


t? 


' copy structure to memory 


unlock the block 








we must copy the memory block data back into the structures. 


the selection. 





This is 


Comments here are omitted for 


Windows API Guide: PrintDlg Function 


CopyMemory printn 


ames, ByVal pNames, Len(printnames) 











retval = GlobalUnlock (pd.hDevNames) 
' Now, display the information we want. We could instead use this info to print 
something. 











Cl 
= 


se 














End If 


' No matter what, 


retval 








retval 


Category: Common Dialog 


Debug.Print "Prin 
Debug.Print "Number of Copies:"; pd.nCopies 


' 


Debug.Print 
End If 














only one 








ter Name: "; printmode.dmDeviceName 



























































Debug.Print "Orientation: "; 
If printmode.dmOrientation = DMORIENT_PORTRAIT Then Debug.Print "Portrait" Else 
Debug.Print "Landscape" 
If (pd.flags And PD_SELECTION) = PD_SELECTION Then ' user chose "Selection" 
Debug.Print "Print the current selection." 
Elseif (pd.flags And PD_PAGENUMS) = PD_PAGENUMS Then ' user chose a page range 
Debug.Print "Print pages"; pd.nFromPage; "to"; pd.nToPage 





left is "All" 





"Print all pages." 


we have to deallocate the memory blocks from before. 


GlobalFree (pd. hDevMode) 
GlobalFree (pd. hDevNames) 





Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 








E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/p/printdlg.html 
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PrinterProperties Function 











Declare Function PrinterProperties Lib "winspool.drv" (ByVal hWnd As Long, ByVal 
hPrinter As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


PrinterProperties displays the Properties dialog box for a specific printer. This dialog allows the user to configure the printer, 
and its look generally depends on the make and model of printer. The dialog is opened modally -- your program pauses 
execution until the user exits the dialog. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get the 
error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window opening the dialog box. 
hPrinter 
A handle to the printer to display the Properties dialog box for. 


Example 


Display the Properties dialog box for the system's default printer. The dialog box is opened when the user clicks the button 
cmdProperties. To use the example, first place a command button named cmdProperties on a form window. 
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' This code is licensed according to the tern 


' Declarations and such needed for the example: 





' (Copy them 
Type P 


Public 





Public 





As Long, 





to the 











(declarations) 


RINTER INFO 1 





flags As Long 


P 





Description As String 
pName As String 


pComment As String 


End Type 





flags As Long, 
ByVal name As String, 


Declare Function 





pcbNeeded As Long, 





EnumPrinters Lib 


section of 

































































pcReturned As Long) 


ByVal Level As Long, 


a module.) 


"winspool.drv" Alias 


ns and conditions listed here. 








( 


EnumPrintersA" 








pPrinterl 


As Long 


Enum As Long, 


























ByVal 


ByVal 


cdBuf 


























Public Const PRINTER_ENUM_DEFAULT = &H1 
Public Declare Function lIstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 
As Any, _ 

ByVal lpString2 As Any) As Long 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "l1strlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function OpenPrinter Lib "winspool.drv" Alias "OpenPrinterA" (ByVal 
pPrinterName _ 

As String, phPrinter As Long, pDefault As Any) As Long 
Public Declare Function PrinterProperties Lib "winspool.drv" (ByVal hWnd As Long, 
ByVal hPrinter _ 

As Long) As Long 
Public Declare Function ClosePrinter Lib "winspool.drv" (ByVal hPrinter As Long) As 
Long 


' xx* Place 


Private Sub 


the 








cmdProperties_Click () 





























following code inside a form window. 


KkK* 























































































































Dim pil As PRINTER INFO 1 ' a little info about the printer 

Dim bytesNeeded As Long ' size needed for buffer 

Dim numPrinters As Long ' number of printers enumerated (should be 1) 

Dim buffer() As Long ' buffer for printer information 

Dim slength As Long ' length of string to copy 

Dim hPrinter As Long " handle to the printer 

Dim retval As Long ' generic return value 

' Figure out how much space is needed to store the printer information. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, vbNullString, 1, ByVal 0, 0, 
bytesNeeded, numPrinters) 

' Allocate that much space in the buffer array. 

ReDim buffer(0 To bytesNeeded / 4 =- 1) As Long 

' Get information about the default printer. 

retval = EnumPrinters (PRINTER_ENUM_DEFAULT, vbNullString, 1, buffer(0), 
bytesNeeded, 

bytesNeeded, numPrinters) 
' Make sure we were successful. 
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If retval = 0 Or numPrinters <> 1 Then 
Debug.Print "No default printer or some other error." 
Exit Sub 

End If 











' Copy the data into the structure. 























With pil 
' Copy numerical data directly. 
.flags = buffer (0) 
' Strings require more work, since the buffer holds pointers to them. 
-pDescription = Space (lstrlen (buffer (1))) 
retval = lstrcpy(.pDescription, buffer (1)) 
.pName = Space (lstrlen (buffer (2))) 
retval = lstrcpy(.pName, buffer (2)) 














)) 
retval = lstrc (.pComment, buffer(3)) 
End With 


-pComment = Space (lstrlen (buffer (3) 














' Open the printer. 
retval = OpenPrinter(pil.pName, hPrinter, ByVal CLng(0)) 
If retval <> 0 Then 

' Display the properties dialog. 

retval = PrinterProperties (Me.hWnd, hPrinter) 

" Close the printer. 

retval = ClosePrinter (hPrinter) 

















Else 
Debug.Print "Unable to open printer!" 











End If 








End Sub 





Category 


Printers 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/p/printerproperties.html 
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Process32First Function 








Declare Function Process32First Lib "kernel32.d11" (ByVal hSnapshot As Long, lppe As 
PROCESSENTRY32) As Long 




















Platforms 


Windows 95: Supported. 
Windows 98: Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Description & Usage 


Process32First retrieves information about the first process in the process list contained in a system snapshot. This snapshot 
must have previously been generated using the CreateToolhelp32Snapshot function. 





Return Value 


If successful, the function returns a nonzero value. If an error occured, possibly if there is an empty or nonexistent process list 
in the snapshot, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


hSnapshot 
A handle to the system snapshot created by the CreateToolhelp32Snapshot function. This snapshot contains the process 





list from which the first process is read. 


Ippe 
Receives information about the first process in the snapshot. The dwSize member of this structure must be initialized 
before calling the function. 


Example 


Print a list of all the processes currently running on the computer when the user clicks button Command1. To do this, a 
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snapshot of the running process list is taken, and then each process in it is analyzed. The filename of the process and the 
number of threads owned by it is then displayed. To use this example, place a command button named Command! on a form 


window. 





This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


" (Copy 





them to the (declaratio 


ns) section of a module.) 


Public Declare Function CreateToolhelp32Snapshot Lib "kernel32.d11" (ByVal dwFlags As 
Long, ByVal _ 





) 
Public Const TH32CS_SNAPPROCESS 











th32ProcessID As Long 











Public T 





End Type 
Public D 


Public D 





Public D 
Long 


' xxx P] 


Private 











ype PROCESSENTRY32 
dwSize As Long 
cntUsage As Long 
th32ProcessID As Long 
th32DefaultHeapID As Lo 
th32ModuleID As Long 
cntThreads As Long 
th32ParentProcessID As 
pcPriClassBase As Long 
dwF lags As Long 
szExeFile As String * 2 






































eclare Function Process 
lppe As PROCESSENTRY32) 


eclare Function Process 














As Long 
= &H2 


ng 


Long 


60 


32First Lib "kernel32.d11" (ByVal hSnapshot As Long, 
As Long 


32Next Lib "kernel32.d11" (ByVal hSnapshot As Long, 
































lppe As PROCESSENTRY32) 
eclare Function CloseHa 








As Long 











ace the following code 


Sub Commandi1_Click () 
Dim hSnapshot As Long 


ndle Lib "kernel32.dl11" (ByVal hObject As Long) As 


inside a form window. *** 


' handle to the snapshot of the process list 





Dim processInfo As PROC 














Dim success As Long 
Dim exeName As String 
Dim retval As Long 











' First, make a snapsho 





ESSENTRY32 ' information about a process in that list 








' success of having gotten info on another process 
' filename of the process 
' generic return value 











t of the current process list. 








hSnapshot = CreateToolhelp32Snapshot (TH32CS_SNAPPROCESS, 0) 











' Get information about 








the first process in the list. 


processInfo.dwSize = Len(processInfo) 
success = Process32First (hSnapshot, processInfo) 


' Make sure a handle wa 
If hSnapshot = -1 Then 








Exit Sub 





End If 














s returned. 





Debug.Print "Unable to take snapshot of process list!" 
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' Loop for each process on the list. 

While success <> 0 
' Extract the filename of the process (i.e., remove the empty space) 
exeName = Left (processInfo.szExeFile, InStr(processInfo.szExeFile, 
































vbNullChar) - 1) 











' Display the process name and the number of threads it owns. 
Debug.Print "Process: "; exeName 
Debug.Print " - Number of threads:"; processInfo.cntThreads 











' Get information about the next process, if there is one. 
processInfo.dwSize = Len(processInfo) 
success = Process32Next (hSnapshot, processInfo) 








Wend 


' Destroy the snapshot, now that we no longer need it. 
retval = CloseHandle (hSnapshot) 


End Sub 











See Also 


Process32Next 


Category 


Tool Help 


Back to the Function list. 
Back to the Reference section. 


Last Modified: September 24, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/p/process32first.html 
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Process32First Function 





Declare Function Process32Next Lib "kernel32.dl11" (ByVal hSnapshot As Long, lppe As 
PROCESSENTRY32) As Long 























Platforms 


Windows 95: Supported. 
Windows 98: Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Description & Usage 


Process32Next retrieves information about the next unread process in the process list contained in a system snapshot. This 
snapshot must have previously been generated using the CreateToolhelp32Snapshot function. Calling this function repeatedly, 





after an initial call to Process32First, will allow your program to read the entire process list. 


Return Value 


If successful, the function returns a nonzero value. If an error occured, most likely if there are no more unread processes in the 
list, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


hSnapshot 
A handle to the system snapshot created by the CreateToolhelp32Snapshot function. This snapshot contains the process 
list from which the next unread process is read. 

Ippe 
Receives information about the next unread process in the snapshot. The dwSize member of this structure must be 
initialized before calling the function. 


Example 
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Print a list of all the processes currently running on the computer when the user clicks button Command 1. To do this, a 
snapshot of the running process list is taken, and then each process in it is analyzed. The filename of the process and the 
number of threads owned by it is then displayed. To use this example, place a command button named Command! on a form 


window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 


' (Copy 
Public 


Long, 


D 








Public Const TH32CS_SNAPPROCE 


them to the (declarations) 





eclare Function CreateToolhelp32Snapshot Lib 





ByVal _ 


th32ProcessID As Long) As Long 


&H2 


) 
SS 








Public T 





End Type 
Public D 


Public D 





Public 
Long 


D 


' xxx P] 


Private 





ype PROCESSENTRY32 

dwSize As Long 

cntUsage As Long 
th32ProcessID As Long 
th32DefaultHeapID As Long 
th32ModuleID As Long 
cntThreads As Long 
th32ParentProcessID As Long 
pcPriClassBase As Long 
dwFlags As Long 

szExeFile As String * 260 












































eclare Function Process32First Lib 











ROCESS 
eclare Function 
lppe As PROCESSENTRY32) 
eclare Function CloseHandle Lib 


lppe As P ENTRY32) As Long 























As Long 














ace the following code inside a 


Sub 
Dim 


Command1_Click () 
hSnapshot As Long ' 
processInfo As PROCESS 











Dim 





Process32Next Lib 


"kernel32. 


"kernel32.dl1] 


"kernel32.dl11l" (J 


section of a module.) 


"kernel32.d1l1" (ByVal 





dwFlags As 








dll" (ByVal hSnapshot As Long, 





ByVal hSnapshot As Long, 





" (ByVal hObject As Long) As 








form window. 


informat 


kkk 


handle to the snapshot of the process list 
ENTRY32 '! 


ion about a process in that list 











Dim success As Long : 
exeName As String ' 


retval As Long ' 


S 





Dim 





Dim 








e proc 
value 





' First 
hSnaps 


sF 


hot 








make a snapshot of the current 
CreateToolhelp32Snapshot (T 


proce 














32CS_SNAPPROCESS, 


uccess of having gotten info on another process 
filename of th 
generic return 


ess 


ss list. 
0) 





' Get information about the first process in the list. 





processInfo.dwSize 
success 
' Make s 
If hSnapshot -1 Then 
Debug.Print 
Exit Sub 











End If 











Len (processInfo) 
Process32First (hSnapshot, 





processIn 


ure a handle was returned. 


"Unable to take snapshot of 
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' Loop for each process on the list. 
While success <> 0 
' Extract the filename of the process (i.e., remove the empty space) 



























































xeName = Left (processInfo.szExeFile, InStr(processInfo.szExeFile, 
vbNullChar) - 1) 
' Display the process name and the number of threads it owns. 
Debug.Print "Process: "; exeName 
Debug.Print " - Number of threads:"; processInfo.cntThreads 
' Get information about the next process, if there is one. 
processInfo.dwSize = Len(processInfo) 
success = Process32Next (hSnapshot, processInfo) 
Wend 


' Destroy the snapshot, now that we no longer need it. 
retval = CloseHandle (hSnapshot) 
End Sub 











See Also 


Process32First 


Category 


Tool Help 


Back to the Function list. 
Back to the Reference section. 
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PtinRect Function 








Declare Function PtInRect Lib "user32.dll1" (lpRect As RECT, ByVal x As Long, ByVal 
y As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


PtInRect determines if a point lies inside or outside of a rectangle. Note that Windows considers the left and top edges of 
a rectangle to be inside it, and the right and bottom edges to be outside. The function returns 1 if the point is inside or 0 if 
it is outside. 


IpRect 
The rectangle to look inside. 
x 
The x coordinate of the point to determine if it is inside or outside. 


The y coordinate of the point to determine if it is inside or outside. 


Example: 





' Determine if the mouse cursor is inside or outside of window Forml. 
' This is done by checking the point of the mouse cursor with the rectangle of the 
window. 






































Dim mousept As POINT TYPE ' receives mouse coordinate 
Dim winrect As RECT ' receives rectangle of Formi 
Dim isinside As Long ' receives 1 if inside or 0 if outside 
Dim retval As Long ' return value for other functions 
retval = GetCursorPos (mousept) ' determine the mouse cursor's position 
retval = GetWindowRect (Forml.hWnd, winrect) ' determine Forml's rectangle 
' Check to see if the mouse cursor is located inside of the Formi rectangle 
isinside = PtInRect (winrect, mousept.x, mousept.y) 
If isinside = 1 Then 
Debug.Print "The mouse cursor is currently inside of Forml." 
Else 
Debug.Print "The mouse cursor is currently outside of Forml." 
End If 





Category: Rectangles 
Go back to the alphabetical Function listing. 


http://216.26.168.92/vbapi/ref/p/ptinrect.html (1 of 2) [9/1/2002 5:38:40 PM] 


Windows API Guide: PtInRect Function 


Go back to the Reference section index. 
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PtInRegion Function 








Declare Function PtInRegion Lib "gdi32.d11" (ByVal hRgn As Long, ByVal x As Long, 
ByVal y As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


PtInRegion determines if a given point lies within a region. The point is considered to be inside the region if it is within the 
area bounded by the region. The function returns 0 if the point is not inside the region, or a non-zero value if the point is in 
the region. 


hRgn 
A handle to the region to determine if a given point lies within. 
x 
The x-coordinate of the point to determine if it lies within the region. 


The y-coordinate of the point to determine if it lies within the region. 
Example: 


' Consider a line connecting the upper-right and lower-left corners of the 
' screen, and consider the region made of the upper-left side of this line. 


























Determine 

' if the mouse cursor lies within this region or not. 

Dim swidth As Long, sheight As Long ' width and height of the screen 
Dim hRgn As Long ' handle to the triangular region explained above 
Dim curpos As POINT TYPE ' receives location of mouse cursor 

Dim vertices(0 To 2) As POINT TYPE ' vertices of region to create 
Dim isinside As Long ' receives 0 if not inside, non-zero otherwise 
Dim retval As Long ' generic return value 














' Get the screen's width and height. Use this information to create the region. 
































swidth = GetSystemMetrics (SM_CXSCREEN) ' screen width 

sheight = GetSystemMetrics (SM_CYSCREEN) " screen height 

' Load region's vertices into the array and create it. 

vertices (0).x = 0: vertices(0).y = 0 ' vertex #1: upper-left corner of screen 
vertices(1).x = swidth: vertices(1).y = 0 ' vertex #2: upper-right corner of screen 
vertices(2).x = 0: vertices(2).y = sheight ' vertex #3: lower-left corner of screen 
hRgn = CreatePolygonRgn(vertices(0), 3, ALTERNATE) ' create the region 








' Get the current position of the mouse cursor. 
retval = GetCursorPos (curpos) 








' Determine if the cursor location lies within the region. 
isinside = PtInRegion(hRgn, curpos.x, curpos.y) t is the point in the region? 
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If isinside = 0 Then ' not inside 

Debug.Print "The cursor is not inside the region." 
Else 
Debug.Print "The cursor is inside the region." 
End If 

















' Delete the region to free up resources. 
retval = DeleteObject (hRgn) 








See Also: RectInRegion 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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QueryPerformanceCounter Function 
Declare Function QueryPerformanceCounter Lib "kernel32.d1l1" (lpPerformanceCount As 








LARGE INTEGER) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Required Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


QueryPerformanceCounter obtains the current reading of the system's high-performance timer. The high-performance 
timer is a counter that the system increments many times a second. To find out how quickly the timer is incremented, use 
QueryPerformanceFrequency. If you know its frequency, you can use the high-performance timer to measure small intervals 
of time precisely. However, keep in mind that not all computers support a high-performance timer. 





Return Value 


If the system contains a high-performance timer, the function returns a non-zero value. If the system does not contain such a 
timer, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


[pPerformanceCount 
Receives the current 64-bit value of the computer's high-performance timer, if one exists. 


Example 


Use the high-performance timer to determine how long it takes to calculate the square roots of the first 100,000 positive 
integers. Run this test when the user clicks on button Command1. Obviously, to use this example, you need to place a 
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command button named Command1 on a form window. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type LARGE INTEGER 
LowPart As Long 
HighPart As Long 
End Type 
Public Declare Function QueryPerformanceFrequency Lib "kernel32.dl11" (lpFrequency As 
LARGE INTEGER) As Long 
Public Declare Function QueryPerformanceCounter Lib "kernel32.d1l1" 
(lpPerformanceCount As LARGE INTEGER) 
As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 


















































This function converts the data in a LARGE INTEGER structure into 














' the form of VB's 64-bit Currency data type. For more information about how this 
works, 

" go to http://www.vbapi.com/articles/64bit/index.html. 

Public Function LI2Curr (li As LARGE INTEGER) As Currency 








Dim temp As Currency 

CopyMemory temp, li, 8 

LI2Curr = temp * 10000 
End Function 





' *** Place the following code inside the form. *** 
Private Sub Command1_Click () 





















































Dim freq As Currency ' high-performance timer frequency 
Dim countl As Currency ' timer reading before calculation 
Dim count2 As Currency ' timer reading after calculation 
Dim bufferl As LARGE INTEGER ' data input buffer for... 
Dim buffer2 As LARGE INTEGER ' ...timer functions 

Dim c As Long ' counter variable 

Dim result As Double ' result of square root calculation 
Dim retval As Long ' generic return value 

















' Get the frequency of the high-performance timer and, in the process, 

' determine if it actually exists or not. 

retval = QueryPerformanceFrequency (bufferl1) 

If retval = 0 Then 
Debug.Print "This computer does not have a high-performance timer." 
Exit Sub 





End If 
freq = LI2Curr (buffer1) 





Time how long it takes to calculate the first 100,000 positive integer 
square roots. Do this by comparing the high-performance timer reading 
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before 

' and after the series of calculations. 

retval = QueryPerformanceCounter (bufferl1) 

For c = 1 To 100000 

result = Sqr(c) 

Next c 

retval = QueryPerformanceCounter (buffer2) 

' Calculate the time interval between measurements. 

countl = LI2Curr (bufferl) 

count2 = LI2Curr (buffer2) 

Debug.Print "The calculation took"; (count2 - countl) / freq; "seconds." 
End Sub 


See Also 


QueryPerformanceFrequency 


Category 


Timers 


Back to the Function list. 
Back to the Reference section. 


Last Modified: August 26, 2000 
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QueryPerformanceFrequency Function 
Declare Function QueryPerformanceFrequency Lib "kernel32.d1l1" (lpFrequency As 


LARGE INTEGER) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Required Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


QueryPerformanceFrequency obtains the frequency of the system's high-performance timer. This value indicates the 
number of times the high-performance timer increments itself every second. Knowing this frequency, you can use 
QueryPerformanceCounter to measure precise time intervals. However, not all systems support a high-performance timer. 





Return Value 


If the system contains a high-performance timer, the function returns a non-zero value. If the system does not contain such a 
timer, the function returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpFrequency 
Receives the 64-bit frequency of the computer's high-performance timer, if one exists. 


Example 


Use the high-performance timer to determine how long it takes to calculate the square roots of the first 100,000 positive 
integers. Run this test when the user clicks on button Command1. Obviously, to use this example, you need to place a 
command button named Command! on a form window. 
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This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type LARGE INTEGER 
LowPart As Long 
HighPart As Long 
End Type 
Public Declare Function QueryPerformanceFrequency Lib "kernel32.dl1" (lpFrequency As 
LARGE INTEGER) As Long 
Public Declare Function QueryPerformanceCounter Lib "kernel32.d11" 
(lpPerformanceCount As LARGE INTEGER) 
As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 


















































This function converts the data in a LARGE INTEGER structure into 














" the form of VB's 64-bit Currency data type. For more information about how this 
works, 

' go to http://www.vbapi.com/articles/64bit/index.html. 

Public Function LI2Curr (li As LARGE INTEGER) As Currency 








Dim temp As Currency 

CopyMemory temp, li, 8 

LI2Curr = temp * 10000 
End Function 





' *** Place the following code inside the form. *** 
Private Sub Command1_Click () 





















































Dim freq As Currency ' high-performance timer frequency 
Dim countl As Currency ' timer reading before calculation 
Dim count2 As Currency ' timer reading after calculation 
Dim bufferl As LARGE INTEGER ' data input buffer for... 
Dim buffer2 As LARGE INTEGER ' ...timer functions 

Dim c As Long ' counter variable 

Dim result As Double ' result of square root calculation 
Dim retval As Long ' generic return value 




















' Get the frequency of the high-performance timer and, in the process, 

' determine if it actually exists or not. 

retval = QueryPerformanceFrequency (bufferl1) 

If retval = 0 Then 
Debug.Print "This computer does not have a high-performance timer." 
Exit Sub 

End If 

freq = LI2Curr (bufferl) 





Time how long it takes to calculate the first 100,000 positive integer 
square roots. Do this by comparing the high-performance timer reading 





before 
' and after the series of calculations. 
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retval = QueryPerformanceCounter (bufferl1) 
For c = 1 To 100000 
result = Sqr(c) 
Next c 
retval = QueryPerformanceCounter (buffer2) 





" Calculate the time interval between measurements. 
































countl = LI2Curr (bufferl1) 

count2 = Li2Curr (buffer2) 

Debug.Print "The calculation took"; (count2 - countl) / freq; "seconds." 
End Sub 
See Also 


QueryPerformanceCounter 


Category 


Timers 


Back to the Function list. 
Back to the Reference section. 
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ReadFile Function 


Declare Function ReadFile Lib "kernel32.d11" (ByVal hFile As Long, lpBuffer 
As Any, ByVal nNumberOfBytesToRead As Long, lpNumberOfBytesRead As Long, 
lpOverlapped As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


ReadFile reads the desired amount of bytes from a file. The file must of course have been opened with at least 
read-level access. If the file is synchronous (not overlapped), the function begins reading the file from the current 
position of the file pointer, and the function automatically adjusts the file pointer to point to the byte immediately 


after the last byte read. If the file is asynchronous (overlapped), the structure passed as /pOverlapped identifies the 
point to begin reading from, and the program calling the function is responsible for updating the file pointer. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful (including if the 
function attempted to read past the end of the file), the function returns a non-zero value. 


Visual Basic-Specific Issues 


When passing a string as /pBuffer to receive the data read from the file, the ByVal keyword must preceed the 
string. The keyword is not necessary for any other data types passed for lpBuffer. When passing 0 for 
lpOverlapped, the expression ByVal CLng(0) must be used. 


Parameters 
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hFile 

A handle to the file to read from. The file must have at least read-level access. 
lpBuffer 

The variable, array, or structure which receives the data read from the file. 
nNumberOfBytesToRead 

The number of bytes of data to read from the file and put into /pBuffer. 
lpNumberOfBytesRead 

Receives the number of bytes of data actually read from the file. If this is less than 

IpNumberOfBytesToRead, the function has attempted to read beyond the end of the file. 
lpOverlapped 

If the file is asynchronous (overlapped), this is an OVERLAPPED structure specifying where to begin 

reading from. If the file is synchronous (not overlapped), this must be 0. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Read both a Long (32-bit) number and a String from the file 

' C:\Test\myfile.txt. Notice how the ByVal keyword must be used 
' when reading a string variable. 

Dim longbuffer As Long ' receives long read from file 

Dim stringbuffer As String ' receives string read from file 

Dim numread As Long ' receives number of bytes read from file 
Dim hFile As Long ' handle of the open file 

Dim retval As Long ' return value 





" Open the file for read-level access. 
hFile = CreateFile("C:\Test\myfile.txt", GENERAL READ, FILE_SHARE_READ, ByVal 
CLng (0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0) 
If hfile = -1 Then ' the file could not be opened 
Debug.Print "Unable to open the file -- it probably does not exist." 
End ' abort the program 
End If 












































' Read a Long-type number from the file 
retval = ReadFile(hFile, longbuffer, Len(longbuffer), numread, ByVal CLng(0) ) 





If numread < Len(longbuffer) Then ' EOF reached 

Debug.Print "End of file encountered -- could not read the data." 
Else 

Debug.Print "Number read from file:"; longbuffer 
End If 





' Read a 10-character string from the file 

stringbuffer = Space(10) ' make room in the buffer 

retval = ReadFile(hFile, ByVal stringbuffer, 10, numread, ByVal CLng(0) ) 
If numread = 0 Then ' EOF reached 
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Debug.Print "End of file encountered -- could not read any data." 
ElseIf numread < 10 Then ' read between 0 and 10 bytes 

Debug.Print "Incomplete string read: "; Left (stringbuffer, numread) 
Else 





Debug.Print "String read from file: "; stringbuffer 
End If 





" Close the file. 
retval = CloseHandle (hFile) 





See Also 


SetFilePointer, WriteFile 


Category 


Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Rectangle Function 
Declare Function Rectangle Lib "gdi32.dll1" (ByVal hdc As Long, ByVal X1 As Long, 





ByVal Y1 As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 
Rectangle draws a rectangular-shaped box on a graphics-capable device. The rectangle is drawn in the device's current 


drawing color and is filled using its current filling color and brush, if any. The function returns 0 if an error occured, or 1 
if successful. 


hdc 

The device context of the object to draw on. 
XI 

The x coordinate of the rectangle's upper-left corner. 
Yl 

The y coordinate of the rectangle's upper-left corner. 
X2 

The x coordinate of the rectangle's lower-right corner. 
Y2 

The y coordinate of the rectangle's lower-right corner. 
Example: 





' Draw a green rectangle on window Forml with an upper-left 
' corner of (25,30) and a lower-right corner of (100,50) 








Dim retval As Long ' return value 

Forml.ForeColor = RGB(0, 255, 0) ' set the foreground-drawing color to green 
retval = Rectangle (Forml.hdc, 25, 30, 100, 50) ' draw the rectangle from (25,30)- 
(100,50) 


See Also: RoundRect 
Category: Filled Shapes 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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Declare Function RectInRegion Lib "gdi32.dll" (ByVal hRgn As Long, lpRect As RECT) 


As Long 


Platforms: Win 32s, Win 95/98, Win NT 


RectInRegion determines if a rectangle lies within a given region. The rectangle is considered to be inside the region if any 
portion of it -- not necessarily all of it -- lies within the region. The function returns 0 if the rectangle is completely outside 


the region, or a non-zero value if the rectangle is at least partially within the region. 


hRgn 

A handle to the region to determine if the rectangle lies within. 
[pRect 

The rectangle to determine if it lies at least partially within the region. 


Example: 


Consider a line connecting the upper-right and lower-left corners of the 
screen, and consider the region made of the upper-left side of this line. 




















Determine 

' if window Forml at least partially lies within the region.. 

Dim swidth As Long, sheight As Long ' width and height of the screen 
Dim hRgn As Long ' handle to the triangular region explained above 
Dim winrect As RECT ' receives Forml's rectangle 

Dim vertices(0 To 2) As POINT TYPE ' vertices of region to create 
Dim isinside As Long ' receives 0 if not inside, non-zero otherwise 
Dim retval As Long ' generic return value 














' Get the screen's width and height. Use this information to create the region. 





























swidth = GetSystemMetrics (SM_CXSCREEN) ' screen width 

sheight = GetSystemMetrics (SM_CYSCREEN) ' screen height 

' Load region's vertices into the array and create it. 

vertices(0).x = 0: vertices(0).y = 0 ' vertex #1: upper-left corner of screen 
vertices(1).x = swidth: vertices(1).y = 0 ' vertex #2: upper-right corner of screen 
vertices (2).x = 0: vertices(2).y = sheight ' vertex #3: lower-left corner of screen 
hRgn = CreatePolygonRgn (vertices(0), 3, ALTERNATE) ' create the region 








Get the rectangle of window Forml, identifying the corners of the window. 
retval = GetWindowRect (Forml.hWnd, winrect) 








Determine if the rectangle lies within the region. 
isinside = RectInRegion(hRgn, winrect) ' is the rectangle in the region? 
If isinside = 0 Then ' not inside 
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Debug.Print "Forml is completely outside the region." 
Else 
Debug.Print "Forml lies at least partially inside the region." 
End If 

















" Delete the region to free up resources. 
retval = DeleteObject (hRgn) 














See Also: PtInRegion 
Category: Regions 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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recv Function 








Declare Function recv Lib "wsock32.d1ll1" (ByVal s As Long, buf As Any, ByVal length As 
Long, ByVal flags As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


recy receives data from a connected socket. The socket must have already been connected to a network host via connect. If no 
response is heard from the network host, the function times out and reports an error. 


Return Value 


If successful, the function returns the number of bytes successfully read from the socket. If an error occured (for example, if 
the connection timed out), the function returns SOCKET_ERROR (use WSAGetLastError to get the error code). 





Visual Basic-Specific Issues 


If specifying a string for buf, the ByVal keyword must be placed in front of it. See the example for a demonstration. 


Parameters 


A descriptor of the connected socket to receive data from. 
buf 
A buffer that receives the information obtained from the connection. This buffer must be large enough to receive the 
amount of data requested. 
length 
The size in bytes of the buffer passed as buf. 
flags 
A combination of the following flags specifying additional options: 
MSG_OOB 
Process out-of-band data only. 
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MSG_PEEK 
Peek at the incoming data by copying data into the buffer without removing it from the input queue. If this flag 
is specified, the function returns the number of bytes of data currently pending to be received. 


Constant Definitions 

















Const SOCKET ERROR = -1 
Const MSG_OOB = &H1 
Const MSG_PEEK = &H2 

















Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 
HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 





Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 


called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 
had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.d1l1" (ByVal wVersionRequested As 





























Integer, lpWSAData _ 
As WSADATA) As Long 















































Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 

Public Const AF_INET = 2 

Public Const SOCK_STREAM = 1 

Public Declare Function gethostbyname Lib "wsock32.dll" (ByVal name As String) As 
Long 

Public Type hostent 


h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
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End Type 
Public Declare Function htons Lib 
Integer 
Public Declare Function socket Lib 


As Long, 





ByVal protocol As Long) 
Public Type sockaddr 





sin_family As Integer 
Sin_port As Integer 
Sin_addr As Long 
Sin_zero As String * 8 






































"wsock32.dl11" 








"wsock32.dl1l1" ( 


As Long 


(ByVal hostshort As 








Integer) As 








ByVal af As Long, ByVal prototype 












































End Type 
Public Declare Function connect Lib "wsock32.d1ll1" (ByVal s As Long, name As sockaddr, 
ByVal namelen _ 

As Long) As Long 
Declare Function ioctlsocket Lib "wsock32.dl11" (ByVal s As Long, ByVal cmd As Long, 
argp As Long) As Long 
Public Const FIONBIO = &H8004667E 
Public Declare Function send Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 

ByVal flags As Long) As Long 
Public Declare Function reev Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 

ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 

As Any, ByVal Length As Long) 








=l 








Public Const SOCKET_ERROR 























' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As 
MAKEWORD = Val("&H" & Right ("00" 








2)) 
End Function 





' xx* Place the following code inside the 


cmdDownload_Click () 
wsockinfo As WSADATA 
sock As Long 

n pHostinfo As Long 
hostinfo As hostent 
piPAddress As Long 
ipAddress As Long 
sockinfo As sockaddr 


Private Sub 
im 








Dim 





Lo ky 
- H- is 
= 





a a g 
‘af 
H 
[æ] 

3 3 3 


im buffer As String 
reply As String 


retval As Long 





im 














im 








' Begin a Winsock session. 


' 








Byte, 





form 


info about 
the socket 
pointer to 
info about 





pointer to 
host's 





ByVal bHigh As Byte) As Integer 
& Hex(bHigh), 2) & Right("00" & Hex(bLow), 
window. *** 
Winsock 
descriptor 


info about the host computer 
the host computer 


host's IP address 


IP address 


settings for the socket 


£ 








buffer for 





sending and receiving data 


accumulates server's reply 
generic return value 
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retval = WSAStartup (MAKEWORD (2, 2), wsockinfo) 

If retval <> 0 Then 

Debug.Print "Unable to initialize Winsock! --"; retval 
Exit Sub 

















End If 














' Get information about the server to connect to. 











pHostinfo = gethostbyname ("www.vbapi.com") 

If pHostinfo = 0 Then 
Debug.Print "Unable to resolve host!" 
GoTo Cleanup 





End If 

' Copy information about the server into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "Couldn't get IP address of www.vbapi.com!" 
GoTo Cleanup 
























































End If 

' Get the server's IP address out of the structure. 
CopyMemory plIPAddress, ByVal hostinfo.h_addr_list, 4 
CopyMemory ipAddress, ByVal plIPAddress, 4 























' Create a socket. 

sock = socket (AF_INET, SOCK _STREAM, 0) 

If sock = SOCKET_ERROR Then 
Debug.Print "Unable to create socket!" 
GoTo Cleanup 























End If 





Make a connection to www.vbapi.com:80 (where the web server listens). 
With sockinfo 

" Use Internet Protocol (IP) 
.Sin_family = AF_INET 


























" Connect to port 80. 
-Sin_port = htons (80) 
' Connect to this IP address. 








.-Sin_addr = ipAddress 
' Padding characters. 
-Sin_zero = String(8, vbNullChar) 








End With 
Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, Len(sockinfo) ) 








If retval <> 0 Then 
Debug.Print "Unable to connect!" 
GoTo Cleanup 














' Send an HTTP/GET request for the / document. 
buffer = "GET / HTTP/1.1" & vbCrLf & _ 

"Host: www.vbapi.com" & vbCrLf & _ 

"User-Agent: HTTP-Test-Program" & vbCrLf & vbCrLf 
retval = send(sock, ByVal buffer, Len(buffer), 0) 
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Debug.Print "Sent request. Waiting for reply..." 








' Make the socket non-blocking, so calls to recv don't halt the program 
waiting for input. 
retval = ioctlsocket (sock, FIONBIO, 1) 








' Read the response from the other system. A more sophisticated program 
' would watch to see if the connection ever times out (i.e., if the 
connection is 
' lost). For brevity, such code is omitted here. 
Do 








buffer Space (4096) 

retval = recv (sock, ByVal buffer, Len (buffer), 0) 

If retval <> 0 And retval <> SOCKET_ERROR Then 
reply = reply & Left (buffer, retval) 
































End If 

' Process background events so the program doesn't appear to freeze. 
DoEvents 

Loop Until retval = 0 











' Print the response from the server. 
Debug.Print "Document Retrieved:" 
Debug.Print reply 




















' Perform the necessary cleanup at the end. 
Cleanup: 

retval = closesocket (sock) 

retval = WSACleanup () 
End Sub 


See Also 


recv 


Category 
Winsock 


Back to the Function list. 





Back to the Reference section. 


Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/recv.html 
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vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 





shop.com | 
RegCloseKey Function 
Declare Function RegCloseKey Lib "advapi32.d1l1" (ByVal hKey As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegCloseKey closes a registry key that had previously been opened with RegCreateKeyEx or RegOpenKeyEx. Your program 
should use this function once it is finished using the registry key, in order to free resources. Obviously, you can no longer use 
the key after closing it. 


Return Value 


If successful, the function returns zero. If an error occured, the function returns a non-zero error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


hKey 
A handle to the registry key to close. 


Example 


This example creates a new registry called "HKEY_CURRENT_USER\Software\MyCorp\MyProgram\Config". Under that 
key, it creates a "username" value and sets its value to the string "Rimmer". Place a command button named Command! in a 
form window to run this example. The example executes when Command! is clicked. 


' This code is licensed according to the terms and conditions listed here. 
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pened 














re 





stringbuit 
tval As Long 











secattr As Sl 












































ECURITY ATTRI 


ES ' 





BUT 




















' Se 








subkey = 





"Sof 


secattr.nLength 


secattr. 





lpSecuri 


secattr.bInherit 


" Create 


(or ope 








n) 


subkey As String 
neworused As Long 


ffer As String 


1 








security settings 











Declarations and such needed for the example: 
(Copy them to the (declarations) section of a module.) 
ublic Type SECURITY ATTRIBUTES 

nLength As Long 

lpSecurityDescriptor As Long 

bInheritHandle As Long 

End Type 
ublic Declare Function RegCreateKeyEx Lib "advapi32.d11" Alias "RegCreateKeyExA" 
ByVal _ 

hKey As Long, ByVal lpSubKey As String, ByVal Reserved As Long, ByVal lpClass 

As String, ByVal dwOptions As Long, ByVal samDesired As Long, 
pSecurityAttributes _ 

As SECURITY ATTRIBUTES, phkResult As Long, lpdwDisposition As Long) As Long 
ublic Declare Function RegSetValueEx Lib "advapi32.d1l1" Alias "RegSetValueExA" 
ByVal _ 

hKey As Long, ByVal lpValueName As String, ByVal Reserved As Long, ByVal 
wType _ 

As Long, lpData As Any, ByVal cbData As Long) As Long 
ublic Declare Function RegCloseKey Lib "advapi32.d1ll1" (ByVal hKey As Long) As Long 
ublic Const HKEY_CURRENT_USER = &H80000001 
ublic Const KEY _WRITE = &H20006 
ublic Const REG_SZ = 1] 

xxx Place the following code inside the form. *** 
rivate Sub Commandl_Click () 
Dim hKey As Long ' receives handle to the registry key 





for the key 


name of the subkey to create or open 


receives 





for 








flag 


if 








the key was created or 





the string to put into the registry 
return value 


0 


the registry key. 





retval = RegCreateKey 


End If 





' Write 
ast 














Ex (HK 








secattr, 


hKey, 
If retval <> 0 Then 
Debug.Print 











Exit Sub 





r beca 





' parame 


us 


WwW 


ar 


EY CURR! 


neworused) 


the string to the registry. 





ENT_USER, 





subkey, 


the name of the new key and the default security settings 
tware\MyCorp\MyProgram\Config" 
Len (secattr) 
tyDescriptor 
Handle 





K 











0, "", 0, KEY_WR 





Error opening or creating registry key -- aborting." 





passing a string. 
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Note the use of 








ByVal in the second-to- 





Windows API Guide: RegCloseKey Function 





stringbuffer = "Rimmer" & vbNullChar ' the terminating null is necessary 
retval = RegSetValueEx(hKey, "username", 0, REG_SZ, ByVal stringbuffer, 





























Len (stringbuffer) ) 





' Close the registry key. 
retval = RegCloseKey (hKey) 
End Sub 





See Also 


RegCreateKeyEx, RegOpenKeyEx 





Category 
Registry 


Go back to the Function listing. 
Go back to the Reference section index. 





Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/regclosekey.html 
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vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





RegCreateKeyEx Function 








Declare Function RegCreateKeyEx Lib "advapi32.dl1" Alias "RegCreateKeyExA" (ByVal 
hKey As Long, ByVal lpSubKey As String, ByVal Reserved As Long, ByVal lpClass As 
String, ByVal dwOptions As Long, ByVal samDesired As Long, lpSecurityAttributes As 
SECURITY ATTRIBUTES, phkResult As Long, lpdwDisposition As Long) As Long 





















































Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegCreateKeyEx creates a new registry key. If the key you want to create already exists, the existing key will be opened (as if 
RegOpenKeyEx had been used). A handle to the created/opened key is put into the variable passed as phkResult. 





Return Value 


If successful, the function returns zero. If an error occured, the function returns a non-zero error code. 


Visual Basic-Specific Information 


None. 


Parameters 


hKey 
Specifies an existing registry under which the new registry key will be created. This is either a handle to an open 
registry key or exactly one of the following flags that identify a registry base key. (The base key flags are named 
identically to the base keys they specify.) 
HKEY_CLASSES_ROOT 
HKEY_CURRENT_CONFIG 
HKEY_CURRENT_USER 
HKEY_DYN_DATA (Windows 95, 98 only) 
HKEY_LOCAL_MACHINE 
HKEY_PERFORMANCE_DATA (Windows NT, 2000 only) 
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HKEY_USERS 
lpSubkey 
The name of the new key to create. 
Reserved 
Reserved -- set to 0. 
IpClass 
The name of the class or object type of the key. You can specify an empty string. 
dwOptions 


If this is 0, the key will be saved to the registry. If this is 1, the key will not be permanently saved to the registry, and 
will disappear when Windows shuts down. 
samDesired 
One or more of the following flags specifying the desired read/write access: 
KEY_ALL_ACCESS 
Permission for all types of access. 
KEY _CREATE_LINK 
Permission to create symbolic links. 
KEY CREATE SUB_KEY 
Permission to create subkeys. 
KEY ENUMERATE _SUB_KEYS 
Permission to enumerate subkeys. 
KEY_ EXECUTE 
Same as KEY_READ. 
KEY_NOTIFY 
Permission to give change notification. 
KEY _QUERY_VALUE 
Permission to query subkey data. 
KEY_READ 
Permission for general read access. 
KEY_SET_VALUE 
Permission to set subkey data. 
KEY_WRITE 
Permission for general write access. 
lpSecurityAttributes 
Windows NT, 2000: Specifies the security attributes to assign to the newly created key. Windows 95, 98: Ignored. 
phkResult 
Receives a handle to the newly created or opened registry key. 
lpdwDisposition 
Receives | if the registry key was newly created, or 2 if an existing key was simply opened. 


Constant Definitions 



































































































































Const HKEY_ CLASSES ROOT = &H80000000 
Const HKEY_CURRENT_CONFIG = &H80000005 
Const HKEY_CURRENT_USER = &H80000001 
Const HKEY_DYN_DATA = &H80000006 

Const HKEY LOCAL MACHINE = &H80000002 
Const HKEY PERFORMANCE DATA = &H80000004 
Const HKEY_USERS = &H80000003 

Const KEY_ALL ACCESS = &HFOO3F 

Const KEY_CREATE LINK = &H20 

Const KEY CREATE SUB_KEY = &H4 
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Const KEY_ENUMERATE SUB _KEYS = &H8 
Const KEY_EXECUTE = &H20019 

Const KEY NOTIFY = &H10 

Const KEY QUERY _VALUE = &H1 

Const KEY READ = &H20019 

Const KEY _SET VALUE = &H2 

Const KEY_WRITE = &H20006 











Example 


This example creates a new registry called "HKEY_CURRENT_USER\Software\MyCorp\MyProgram\Config". Under that 
key, it creates a "username" value and sets its value to the string "Rimmer". Place a command button named Command] in a 
form window to run this example. The example executes when Command! is clicked. 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 


' (Copy them 
Public Type SECURITY ATTRIBUT 














the (declarations) 


ES 


CO 

















nLength As Long 











lpSecurityDescriptor As Long 





bInheritHandle As Long 




























































































P 


section of 


a module.) 



































ns and conditions listed here. 











End Type 
Public Declare Function RegCreateKeyEx Lib "advapi32.dll" Alias "RegCreateKeyExA" 
(ByVal _ 

hKey As Long, ByVal lpSubKey As String, ByVal Reserved As Long, ByVal lpClass 

As String, ByVal dwOptions As Long, ByVal samDesired As Long, 
lpSecurityAttributes _ 

As SECURITY ATTRIBUTES, phkResult As Long, lpdwDisposition As Long) As Long 
Public Declare Function RegSetValueEx Lib "advapi32.d1l1" Alias "RegSetValueExA" 
(ByVal _ 

hKey As Long, ByVal lpValueName As String, ByVal Reserved As Long, ByVal 
dwType _ 

As Long, lpData As Any, ByVal cbData As Long) As Long 
Public Declare Function RegCloseKey Lib "advapi32.dll" (ByVal hKey As Long) As Long 
Public Const HKEY_CURRENT_USER = &H80000001 
Public Const KEY _WRITE = &H20006 
Public Const REG_SZ = 1 


' **x** Place 


Private Sub 


opened 














Command1_Click () 
hKey As Long 


im 


the following code inside the 





form. 


kKkK* 


receives handle to the registry key 











im 


secattr As SECURITY ATTRI 





BUT 





ES 











subkey As String 
neworused As Long 





stringbuffer As String 
retval As Long 














security settings 





for the key 


name of the subkey to create or open 





receives flag for if the key was created or 





the string to put into the registry 
return value 
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' Set the name of the new key and the default security settings 




















subkey = "Software\MyCorp\MyProgram\Config" 
secattr.nLength = Len(secattr) 
secattr.lpSecurityDescriptor = 0 

















secattr.bInheritHandle = 1 


' Create (or open) the registry key. 

retval = RegCreateKeyEx (HKEY_CURRENT_USER, subkey, 0, "", 0, KEY_WRITE, 
secattr, hKey, neworused) 

If retval <> 0 Then 




























































































Debug.Print "Error opening or creating registry key -- aborting." 
Exit Sub 
End If 
' Write the string to the registry. Note the use of ByVal in the second-to- 
last 
' parameter because we are passing a string. 
stringbuffer = "Rimmer" & vbNullChar ' the terminating null is necessary 
retval = RegSetValueEx(hKey, "username", 0, REG_SZ, ByVal stringbuffer, 
Len (stringbuffer) ) 
' Close the registry key. 
retval = RegCloseKey (hKey) 
End Sub 





See Also 


RegCloseKey, RegDeleteKey, RegOpenKeyEx 


Category 


Registry 


Go back to the Function listing. 
Go back to the Reference section index. 





Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/regcreatekeyex.html 
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vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





RegDeleteKey Function 





Declare Function RegDeleteKey Lib "advapi32.dl1" Alias "RegDeleteKeyA" (ByVal hKey 
As Long, ByVal lpSubKey As String) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegDeleteKey deletes a key from the registry, along with any values it may contain. Windows NT, 2000: The function will 
fail if there are any subkeys under the key to delete. Windows 95, 98: The function will delete any subkeys under the key to 
be deleted, instead of failing. 


Return Value 


If successful, the function returns zero. If an error occured, the function returns a nonzero error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


hKey 
Specifies an existing registry key that the key to delete is under. This is either a handle to an open registry key or one 
of the following flags that identify a registry base key. (The base key flags are named identically to the base keys they 
specify.) 
HKEY_CLASSES_ROOT 
HKEY_CURRENT_CONFIG 
HKEY_CURRENT_USER 
HKEY_DYN_DATA (Windows 95, 98 only) 
HKEY_LOCAL_MACHINE 
HKEY_PERFORMANCE_DATA (Windows NT, 2000 only) 
HKEY_USERS 
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IpSubKey 


The name of the subkey under hKey to delete. 


Constant Definitions 


Const HKEY_CLASSES_ROOT = &H80000000 
Const HKEY_CURRENT_CONFIG = 
Const HKEY_CURRENT_USER = &H80000001 
Const HKEY_DYN_DATA = &H80000006 

Const HKEY_LOCAL MACHINE = 


Const HKEY PERFORMANCE DATA 
Const HKEY_USERS 


Example: 


&H80000005 


&H 


= &H80000003 


80000002 
&H80000004 


Attempt to delete the registry key "HKEY_LOCAL_MACHINE\Software\MyProgram\Config" when the user clicks button 
Command1. (Of course, typically you would never give the user an option like this, but this is just a simple example.) 
Depending on your Windows platform, this function may fail if there are any subkeys under this key. To run this example, 
you first need to place a command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 


' (Copy them to the 





Pt 


(declarations) section of a module.) 





Public Declare Function RegDeleteKey Lib "advapi32.d1l1" Alias "RegDeleteKeyA" (ByVal 





hKey As Long, 








ByVal lpSubKey As String) As Long 
Public Const HKEY_LOCAL_ MACHINE = &H80000002 


Private Sub Command1_Click () 


Dim retval 


As Long 





If 





El 


End If 


End Sub 


See Also 


se 


return value 





Debug .!] 
and/or values under it. 
Debug.!] 





Attempt to delet 
retval 


Print 
W 


Print 





Debug.!] 


Print 


RegCreateKeyEx, RegDeleteValue 


Category 


the desired registry key. 
RegDeleteKey (HKEY_LOCAL_MACHINE, "Software\MyProgram\Config") 
retval <> 0 Then 











Delete operation failed. The key may have subkeys 


"Of course, the key might just not exist at all." 





Deletion successful." 
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Registry 


Go back to the Function listing. 
Go back to the Reference section index. 


Last Modified: September 24, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/r/regdeletekey.html 
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RegDeleteValue Function 








Declare Function RegDeleteValue Lib "advapi32.d1l1" Alias "RegDeleteValueA" (ByVal 
hKey As Long, ByVal lpValueName As String) As Long 

















Platforms: Win 95/98, Win NT 


RegDeleteValue deletes a value stored under a specified key in the registry. This function only works with values stored; it 
cannot delete subkeys. The value can of course be of any registry data type. The function returns 0 if successful, or a non- 
zero error code if an error occured. 


hKey 

A handle to the open registry key which contains the value to delete. 
lpValueName 

The name of the value to delete. 


Example: 








' Delete the value "SplashScreen" under the hypothetical registry key 





' "HKEY_LOCAL_MACHINE\Software\MyProgram\Config". Note how error conditions are 
checked. 

Dim hkey As Long ' handle to the open registry key 

Dim retval As Long ' return value 








' First, open up the registry key which holds the value to delete. 
retval = RegOpenKeyEx (HKEY_LOCAL_MACHINE, "Software\MyProgram\Config", 0, 
KEY_ALL_ ACCESS, hkey) 


























If retval = 0 Then ' successfully opened registry key 
" Now delete the desired value from the key. 
retval = RegDeleteValue(hkey, "SplashScreen") ' if it existed, it is now deleted 
" Note that we only have to close the registry key if it was successfully opened. 
retval = RegCloseKey 

End If 





See Also: RegDeleteKey, RegQuery ValueEx, RegSetValueEx 
Category: Registry 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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RegEnumKeyEx Function 

















Declare Function RegEnumKeyEx Lib "advapi32.d11" Alias "“RegEnumKeyExA" (ByVal hKey As 
Long, ByVal dwIndex As Long, ByVal lpName As String, lpcbName As Long, lpReserved As 
Long, ByVal lpClass As String, lpcbClass As Long, lpftLastWriteTime As FILETIME) As 
Long 






































Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegEnumKeyEx enumerates all of the subkeys under a given key. The function retrieves the subkey name, class name, and 
last write time of each subkey. The key under which the subkeys are enumerated must have been opened with subkey- 
enumeration access (see the example). The program must use the function in a loop, incrementing the index value (which 
determines which subkey is identified) until the list has been exhaused. The subkeys are not retrieved in any clear order. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


hKey 
A handle to the open registry key containing the subkeys to be enumerated (having been opened with subkey- 
enumeration access). This could also be one of the following flags identifying a predefined base keys: 
HKEY_CLASSES_ROOT 
The HKEY_CLASSES_ROOT base key. 
HKEY_CURRENT_CONFIG 
The HKEY_CURRENT_CONFIG base key. 
HKEY_CURRENT_USER 
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The HKEY_CURRENT_USER base key. 
HKEY_DYN_DATA 
Windows 95, 98: The HKEY_DYN_DATA base key. 
HKEY_LOCAL_MACHINE 
The HKEY_LOCAL_MACHINE base key. 
HKEY_PERFORMANCE_DATA 
Windows NT, 2000: The HKEY_PERFORMANCE_DATA base key. 
HKEY_USERS 
The HKEY_USERS base key. 
dwIndex 
The index of the particular subkey to retrieve information about. Valid indices begin with O and go up to one less than 
the number of subkeys. 
lpName 
String which receives the name of the subkey whose information is being retrieved. This must be initialized to a 
sufficient size to receive the string. 
lpcbName 
The size of the string passed as JpName. This also receives the length of the string the function places in JpName. 
lpReserved 
Reserved -- set to 0. Visual Basic users must use the ByVal keyword immediately before the 0. 
[pClass 
String which receives the name of the subkey's class. This must be initialized to a sufficient size to receive the string. 
IpcbClass 
The size of the string passed as /pClass. This also receives the length of the string the function places in /pClass. 
lpftLastWriteTime 
Receives the time and date on which the subkey was last written to. 


Constant Definitions 




























































































Const HKEY_ CLASSES ROOT = &H80000000 
Const HKEY CURRENT_CONFIG = &H80000005 
Const HKEY_CURRENT_USER = &H80000001 
Const HKEY_DYN_DATA = &H80000006 

Const HKEY LOCAL MACHINE = &H80000002 
Const HKEY_ PERFORMANCE DATA = &H80000004 
Const HKEY_USERS = &H80000003 
































Example 


' This code is licensed according to the terms and conditions listed here. 





' Enumerate the subkeys under HKEY_LOCAL_MACHINE\Software. The name 
' and class of each subkey is displayed for the user. Note the use of the loop which 
' starts at 0 and keeps incrementing the index until no more subkeys exist. 













































































Dim keyname As String ' receives name of each subkey 

Dim keylen As Long ' length of keyname 

Dim classname As String ' receives class of each subkey 

Dim classlen As Long ' length of classname 

Dim lastwrite As FILETIME ' receives last-write-to time, but we ignore it here 
Dim hkey As Long ' handle to the HKEY_LOCAL_MACHINE\Software key 

Dim index As Long ' counter variable for index 
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Dim retval As Long ' function's return value 

' Open the desired registry key. Note the access level requested. 

retval = RegOpenKeyEx (HKEY_LOCAL MACHINE, "Software", 0, KEY ENUMERATE SUB _ KEYS, 
hkey) 





' Test to make sure the key was opened successfully. 
If retval <> 0 Then 








Debug.Print "Registry key could not be opened -- aborting." 
End ' terminate the program 
End If 











' List through each possible subkey. Note how the strings receiving the information 
' must be reinitialized each loop iteration. 








index = 0 ' initial index value 
While retval = 0 ' while we keep having success (retval equals 0 from the above API 
call) 

keyname = Space(255): classname = Space (255) ' make room in string buffers 

keylen = 255: classlen = 255 ' identify the allocated space 


' Get information about the next subkey, if one exists. 
retval = RegEnumKeyEx (hkey, index, keyname, keylen, ByVal 0, classname, classlen, 
lastwrite) 



























































If retval = 0 ' only display info if another subkey was found 
' Extract the useful information from the string buffers. 
keyname = Left (keyname, keylen) ' trim off the excess space 
classname = Left(classname, classlen) 
' Display the returned information. 
Debug.Print "HKEY_ LOCAL MACHINE\Software\"; keyname ' display full subkey name 
Debug.Print " (class: "; classname ' display subkey's class 

End If 

index = index + 1 ' increment the index counter 

Wend ' end the loop 


' 


Close the registry key after enumeration is complete. 
retval = RegCloseKey (hkey) 





See Also 


RegEnumValue 





Category 


Registry 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





Last Modified: March 19, 2000 
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RegEnumvValue Function 











Declare Function RegEnumValue Lib "advapi32.d11" Alias "RegEnumValueA" (ByVal hKey As 
Long, ByVal dwIndex As Long, ByVal lpValueName As String, lpcbValueName As Long, 
ByVal lpReserved As Long, lpType As Long, lpData As Byte, lpcbData As Long) As Long 





























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegEnum Values enumerates all of the values under a given registry key. The function must be used in a loop because each 
call only retrieves information about the value identified by the given index. Besides merely listing the names of each value, 
the function can also retrieve the data associated with each value. This data, which could be in any vaid registry data format, is 
placed in an array of bytes passed as /pData. It is the program's responsibility to correctly interpret the information. The key 
whose values are enumerated must have been opened with query-level access. The values which are enumerated are not 
retrived in any obvious order. 


Return Value 


If successful, the function returns 0. If an error occured, the function returns a non-zero error code. 


Visual Basic-Specific Issues 


When passing 0 for /pData or IpcbData, the By Val keyword must be placed in front if the 0 (1.e., use By Val 0 instead of just 
0). 


Parameters 


hKey 
A handle to the opened registry key containing the values to enumerate (having been opened with query-level access). 
This could also be exactly one of the following base keys (identified by identicially named flags): 
HKEY_CLASSES_ROOT 
HKEY_CURRENT_CONFIG 
HKEY_CURRENT_USER 
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HKEY_DYN_DATA (Windows 95, 98 only) 
HKEY_LOCAL_MACHINE 
HKEY_PERFORMANCE_DATA (Windows NT, 2000 only) 
HKEY_USERS 
dwIndex 
The index of the particular value to retrieve information about. Valid indices range from 0 to one less than the total 
number of values. 
lpValueName 
String which receives the name of the value whose information is being retrieved. This must be initialized to a 
sufficient size to receive the string. 
lpcbValueName 
The size of the string passed as lpValueName. This also receives the size of the string the function places inside of it. 
lpReserved 
Reserved -- set to 0. 
lpType 
Receives exactly one of the following flags identifying the data type of the value: 
REG_BINARY 
A non-text sequence of bytes. 
REG_DWORD 
Same as REG_DWORD_LITTLE_ENDIAN. 
REG_DWORD_BIG_ENDIAN 
A 32-bit integer stored in big-endian format. This is the opposite of the way Intel-based computers normally 
store numbers -- the byte order is reversed, putting the most significant byte first in memory. 
REG_DWORD_LITTLE_ENDIAN 
A 32-bit integer stored in little-endian format. This is the way Intel-based computers store numbers, putting the 
least significant byte first in memory. 
REG_EXPAND_SZ 
A null-terminated string which contains unexpanded environment variables. 
REG_LINK 
A Unicode symbolic link. 
REG_MULTI_SZ 
A series of strings, each separated by a null character and the entire set terminated by a two null characters. 
REG_NONE 
No data type. 
REG_RESOURCE_LIST 
A list of resources in the resource map. 
REG_SZ 
A string terminated by a null character. 
lpData 
A byte array receiving the data stored in the value. If you do not want to retrieve the data, set this parameter to 0. 
lpcbData 
The size in bytes of the array passed as /pData. This also receives the size in bytes of the data placed into the array. If 
you do not want to retrieve any data, set this parameter to 0. 


Constant Definitions 



























































Const HKEY_ CLASSES ROOT = &H80000000 
Const HKEY CURRENT_CONFIG = &H80000005 
Const HKEY_CURRENT_USER = &H80000001 
Const HKEY_DYN_DATA = &H80000006 

Const HKEY LOCAL MACHINE = &H80000002 
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Const HKEY_ PERFORMANCE DATA = &H80000004 
Const HKEY_USERS = &H80000003 
Const REG _ BINARY = 3 

Const REG _DWORD = 4 

Const REG DWORD_BIG_ENDIAN = 5 
Const REG _DWORD_LITTLE ENDIAN = 4 
Const REG _EXPAND_SZ = 2 

Const REG_LINK = 6 

Const REG MULTI_SZ = 7 

Const REG_NONE = 0 

Const REG _RESOURCE_LIST = 8 

Const REG_SZ = 1 














Example 


List the values under the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion. Display the 
names of all values under the key. Also display the values' data if they are either null-terminated strings or binary data. (This 
example could be extended to include the rest of the registry data types, but it doesn't to save space). Note how the byte array 
is used to buffer the data before it might be copied to the string. 


The example runs when the user clicks button Command1. To use this example, then, you must first place a command button 
named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function RegEnumValue Lib "advapi32.dll" Alias "RegEnumValueA" (ByVal 
hKey _ 























As Long, ByVal dwIndex As Long, ByVal lpValueName As String, lpcbValueName As 
Long, 

















ByVal lpReserved As Long, lpType As Long, lpData As Byte, lpcbData As Long) 
As Long 

Public Declare Function RegOpenKeyEx Lib "advapi32.dll" Alias "RegOpenKeyExA" (ByVal 
hKey _ 
































As Long, ByVal lpSubKey As String, ByVal ulOptions As Long, ByVal samDesired 


As Long, phkResult As Long) As Long 
Public Declare Function RegCloseKey Lib "advapi32.dll" (ByVal hKey As Long) As Long 























Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, 
Source As Any, ByVal Length As Long) 
Public Const HKEY_LOCAL_ MACHINE = &H80000002 
Public Const KEY QUERY _VALUE = &H1 
Public Const REG_SZ = 1 
Public Const REG BINARY = 3 


















































' *** Place the following code inside a form window. *** 





Private Sub Command1_Click () 
Dim valuename As String ' name of the value being retrieved 
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Dim valuelen As Long ' length of valuename 
Dim datatype As Long ' receives data type of value 
Dim data(0O To 254) As Byte ' 255-byte data buffer for read information 
Dim datalen As Long ' size of data buffer information 
Dim datastring As String ' will receive data converted to a string, if 
necessary 
Dim hkey As Long ' handle to the registry key to enumerate th 
values of 
Dim index As Long " counter for the index of the value to enumerat 
Dim c As Long ' counter variable 
Dim retval As Long ' functions' return value 
' Open the registry key to enumerate the values of. 
retval = RegOpenKeyEx (HKEY_LOCAL_MACHINE, 
"Software\Microsoft \Windows\CurrentVersion", 
0, KEY_QUERY_VALUE, hkey) 
" Check to see if an error occured. 
If retval <> 0 Then 
Debug.Print "Registry key could not be opened -- aborting." 
End ' abort the program 
End If 
' Begin enumerating the values. Get each one, displaying its name. If it's 
a null- 
' terminated string or binary data, display it. If not, say so. 
index = 0 ' initialize the counter 
While retval = 0 ' loop while successful 
' Initialize the value name buffer. 
valuename = Space (255) ' 255-space buffer 
valuelen = 255 ' length of the string 
datalen = 255 ' size of data buffer 
' Get the next value to be enumerated 
retval = RegEnumValue(hkey, index, valuename, valuelen, 0, datatype, 
data(0), datalen) 
If retval = 0 Then ' if successful, display information 





' Extract the useful 


and display it. 


string. 


null. 


valuename 








Debug.Print 
" Determine 











in 


formation 





Left (valuename, 
"Value Name: "; 





Select 
Case REG_S 











room in the string 





copy usei 


datastring = Space(datalen - 1) ' 
CopyMemory ByVal datastring, 

ful data 
Debug.Print " Data (string): 





Case 


Copy the 


datatype 
ee T 





valuelen) 
valuename 
the data type of the value and display it. 


null-terminated string 
information from the byte array into the 























Case REG_B 





INARY ' binary data 
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data(0), 





From the value name buffer 


We subtract one because we don't want the trailing 


make just enough 


datalen - 1 J 


"; datastring 
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Display t 


data, separated by 


" sapces. 
assure each byte 
' is repres 


Debug.Print 











For c =O T 
information 
dat 
into hex 
Y oF 
tee 
datastring 
Next c 
Debug.Print 
Case Else ' 
Debug.Print 





that kind of data." 
End Select 








End If 
index = index + 1 ' 
Wend ' end the loop 


' 


Close the registry key. 
retval RegCloseKey (hkey) 


End Sub 








See Also 
RegEnumKeyEx 
Category 


Registry 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


Last Modified: September 24, 2000 


Debug.Print 


he hexadecimal values of each byte of 





Use the datastring buffer to allow us to 


ented by a two-character string. 
" Data (binary):"; 
o datalen - 1 loop through returned 








astring Hex (data (c)) convert value 
f needed, add leading zero (s). 
Len (datastring) < 2 Then datastring 


String(2 - Len(datastring), "0") & 


d 


datastring; 


end the line 


a data type this example doesn't handle 


"This example doesn't know how to read 


increment the index counter 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





Go back to the Windows API Guide home page. 
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RegisterClass Function 











Declare Function RegisterClass Lib "user32.dll" Alias "RegisterClassA" (lpWndClass 
As WNDCLASS) As Long 





Platforms 


e Windows 95: Supported but Obsolete; use RegisterClassEx instead. 

e Windows 98: Supported but Obsolete; use RegisterClassEx instead. 

e Windows NT: Requires Windows NT 3.1 or later but Obsolete in Windows NT 4.0 or later; use RegisterClassEx 
instead. 

e Windows 2000: Supported but Obsolete; use RegisterClassEx instead. 

e Windows CE: Requires Windows CE 1.0 or later. 








Description & Usage 


RegisterClass registers a new window class for use. Only after registering the window class can it be used to create 
windows. This function is unable to set the small icon associated with a window class; to do that, use the more powerful 
RegisterClassEx function. After the window class is completely finished being used, use UnregisterClass to unregister it. 








Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns an 
atom identifying the class. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpWndClass 
Information about the window class being registered. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' Register a new window class. The various properties to 
' give it will be explained in the code. 





' *** Place the following code in a module. *** 

' Define the window procedure to use for the class. Here, we'll 

' just make a wrapper for the default window procedure. 

Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 





Long, ByVal lParam As Long) As Long 
" Return whatever the default window procedure returns. 
WindowProc = DefWindowProc (hWnd, uMsg, wParam, lParam) 











End Function 





' *** Place the following code where you want to register the class. *** 
Dim classinfo As WNDCLASS ' holds info about the class 


Dim classatom As Long ' receives an atom to the class just registered 














" Set the various data members of the structure. 





' Class style: give each window its own DC; redraw when resized. 
classinfo.style = CS_OWNDC Or CS_HREDRAW Or CS_VREDRAW 

Use the window procedure above to process messages. 
lassinfo.lpfnWndProc = AddressOf WindowProc 














= Q 


We aren't using any extra information. 





classinfo.cbClsExtra = 0 
classinfo.cbWndExtra = 0 

' Handle to the instance of this application. 
classinfo.hInstance = App.hInstance 





Use the icon stored in C:\MyApp\deficon.ico. 
classinfo.hIcon = ExtractIcon(App.hInstance, "C:\MyApp\deficon.ico", 0) 














Use the cursor stored in C:\MyApp\mouse.cur. 
classinfo.hCursor = LoadCursorFromFile ("C:\MyApp\mouse.cur") 








Fill the background with the system color for an application's workspace. 
classinfo.hbrBackground = COLOR_APPWORKSPACE 

No menu resource to use. 

classinfo.lpszMenuName = "" 

Give the class a name. 

classinfo.lpszClassName = "CustomClass" 























' Finally, register the class. 
classatom = RegisterClass (classinfo) 
" Now the class CustomClass can be used to create windows. 





' *** Place the following code where you wish to unregister the window class. *** 
Dim retval As Long 














' Unregister the window class. 
retval = UnregisterClass("CustomClass", App.hInstance) 








See Also 
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RegisterClassEx, UnregisterClass 


Category 


Window Classes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 24, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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shop.com | 
RegisterClassEx Function 
Declare Function RegisterClassEx Lib "user32.d11" Alias "RegisterClassExA" (lpwcx As 

















WNDCLASSEX) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


RegisterClassEx registers a new window class for use. Only after registering the window class can it be used to create 
windows. After the window class is completely finished being used, use UnregisterClass to unregister it. 





Return Value 


If an error occured, the function returns 0. If successful, the function returns an atom identifying the class. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpwcx 
Information about the window class being registered. 


Example 


Register a new window class for later use. Although this example doesn't actually use the newly created class, it shows how 
this class would be made and, later, destroyed. The code executes in the Load and Unload logic of a form window Form1. 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WNDCLASSEX 
cbSize As Long 
style As Long 
lpfnWndProc As Long 
cbhClsExtra As Long 
chWndExtra As Long 
hIinstance As Long 
hIcon As Long 
hCursor As Long 
hbrBackground As Long 
lpszMenuName As String 
lpszClassName As String 
hIiconSm As Long 
End Type 
Public Const CS_OWNDC = &H20 
Public Const CS_HREDRAW = &H2 
Public Const CS_VREDRAW = &H1 
Public Const COLOR_APPWORKSPACE = 12 















































Public Declare Function RegisterClassEx Lib "user32.dll1" Alias "RegisterClassExA" _ 
(lpwcx As WNDCLASSEX) As Long 
Public Declare Function UnregisterClass Lib "user32.dl1" Alias "UnregisterClassA" _ 


(ByVal lpClassName As Any, ByVal hInstance As Long) As Long 
Public Declare Function LoadCursorFromFile Lib "user32.dll" Alias 




















"LoadCursorFromFileA" _ 

(ByVal lpFileName As String) As Long 
Public Declare Function ExtractIcon Lib "sShell32.dll1" Alias "ExtractIconA" (ByVal 
hinst _ 

As Long, ByVal lpszExeFileName As String, ByVal nIconIndex As Long) As Long 























' *** Place the following code in a module. *** 


' Define the window procedure to use for the class. Here, we'll 


Pe 


' just make a wrapper for the default window procedure. 


Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 





Long, 
ByVal lParam As Long) As Long 
' Return whatever the default window procedure returns. 
WindowProc = DefWindowProc (hWnd, uMsg, wParam, lParam) 











End Function 


' The following function returns the value passed to it. This allows the 
' example to use the AddressOf operator to set a value in the structure. 
Public Function DummyFunc (ByVal dwValue As Long) As Long 

DummyFunc = dwValue 

End Function 











' *** Place the following code inside window Formi. *** 


Private Sub Form_Load() 
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Dim classinfo As WNDCLASSEX ' holds info about the class 
Dim classatom As Long ' receives an atom to the class just registered 











Load a decription of the new class into the strucure. 
With classinfo 





' Of course, set the size of the structure. 

.cbSize = Len(classinfo) 

' Class style: give each window its own DC; redraw when resized. 
.style = CS_OWNDC Or CS_HREDRAW Or CS_VREDRAW 

' Use the window procedure above to process messages. 
.lpfnWndProc = DummyFunc (AddressOf WindowProc) 




















' We aren't using any extra information. 
.cbClsExtra = 0 

.cbWndExtra = 0 

' Handle to the instance of this application. 
-hinstance = App.hInstance 

' Use the icon stored in C:\MyApp\deficon.ico. 

-hicon = ExtractIcon(App.hInstance, "C:\MyApp\deficon.ico", 0) 














' Use the cursor stored in C:\MyApp\mouse.cur. 

















-hCursor = LoadCursorFromFile("C:\MyApp\mouse.cur") 

' Fill the background with the system color for an application's 
workspace. 

-hbrBackground = COLOR_APPWORKSPACE 

' No menu resource to use. 

-lpszMenuName = "" 

' Give the class a name. 

-lpszClassName = "CustomClass" 

' Use the small icon stored in C:\MyApp\deficonsm.ico. 

-hiconSm = ExtractIcon(App.hInstance, "C:\MyApp\deficonsm.ico", 0) 

End With 


' Finally, register the class. 
classatom = RegisterClassEx (classinfo) 
' Now the class CustomClass can be used to create windows. 








End Sub 





Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 








' Unregister the window class when the form closes. 
retval = UnregisterClass("CustomClass", App.hInstance) 
End Sub 











See Also 





RegisterClass, UnregisterClass 


Category 
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Window Classes 





Go back to the Function listing. 
Go back to the Reference section index. 


Last Modified: July 30, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/r/registerclassex.html 
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RegOpenKeyEx Function 


Declare Function RegOpenKeyEx Lib "advapi32.d1l1l" Alias "RegOpenKeyExA" (ByVal 
hKey As Long, ByVal lpSubKey As String, ByVal ulOptions As Long, ByVal 
samDesired As Long, phkResult As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


RegOpenKeyEx opens a key in the Windows registry. The handle it gives must be used when you read to or write 
from any values under that key. Unlike RegCreateKeyEx, this function will not create the key if it does not exist. 





The function puts a handle to the opened key into the variable passed as phkResult. The function returns 0 if 
successful, or a non-zero value error code if an error occured. 


hKey 
Either the handle to an open registry key or exactly one of the following flags that the desired key is under: 
HKEY_CURRENT_USER = &H80000001 
The HKEY_CURRENT_USER base key, which stores program information for the current user. 
HKEY_LOCAL_MACHINE = &H80000002 
The HKEY_LOCAL_MACHINE base key, which stores program information for all users. 
HKEY_USERS = &H80000003 
The HKEY_USERS base key, which has all the information for any user (not just the one provided by 
HKEY_CURRENT_USER). 
HKEY_CURRENT_CONFIG = &H80000005 
The HKEY_CURRENT_CONFIG base key, which stores computer configuration information. 
HKEY_DYN_DATA = &H80000006 
The HKEY_DYN_DATA base key, which stores dynamic data. 
lpSubKey 
The name of the key to open. 
ulOptions 


Reserved. Set to 0. 
samDesired 

One or more of the following flags specifying the desired read/write access: 

KEY_ALL_ACCESS = &HF003F 
Permission for all types of access. 

KEY_CREATE_LINK = &H20 
Permission to create symbolic links. 

KEY_CREATE_SUB_KEY = &H4 
Permission to create subkeys. 

KEY_ENUMERATE_SUB_KEYS = &H8 
Permission to enumerate subkeys. 
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KEY_EXECUTE = &H20019 

Same as KEY_READ. 
KEY_NOTIFY = &H10 

Permission to give change notification. 
KEY_QUERY_VALUE = &H1 

Permission to query subkey data. 
KEY_READ = &H20019 

Permission for general read access. 
KEY_SET_VALUE = &H2 

Permission to set subkey data. 
KEY_WRITE = &H20006 

Permission for general write access. 

phkResult 

Receives the handle to the registry key. 


Example: 


" Open a key called HKEY_CURRENT_USER\Software\MyCorp\MyProgram\Config. 
' Then create a "username" value under that key and set its value to "Rimmer". 











Dim hregkey As Long ' receives handle to the opened registry key 
Dim subkey As String ' name of the subkey to create 
Dim retval As Long ' return value 


' Set the name of the new key and the default security settings 
subkey = "Software\MyCorp\MyProgram\Config" 


' Open the registry key 
retval = RegOpenKeyEx (HKEY_CURRENT_USER, subkey, 0, KEY_WRITE, hregkey) 
If retval <> 0 Then ' error during open 
Debug.Print "Error opening registry key -- aborting." 
End ' terminate the program 
End If 








" Insert rest of code here..... 


' Close the registry key 
retval = RegCloseKey (hregkey) 





See Also: RegCloseKey, RegCreateKeyEx 
Category: Registry 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www. vbapi.com/ref/r/regopenkeyex.html 
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RegQueryValueEx Function 














Declare Function RegQueryValueEx Lib "advapi32.dll" Alias "RegQueryValueExA" (ByVal 
hKey As Long, ByVal lpValueName As String, ByVal lpReserved As Long, lpType As Long, 
lpData As Any, lpcbData As Long) As Long 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegQuery ValueEx reads a value from a registry key. It can read many different types of data, including integers, strings, and 
any other registry data types. When calling the function, the program does not have to know what the data type of the value 
being read is. Instead, the program receives information telling it what type of data was read. 


Return Value 


If an error occued, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


When putting the data read from the registry into a string, the /pData parameter must be prefixed by the ByVal keyword. The 
ByVal keyword is not necessary with any other data types passed as that parameter. 


Parameters 


hKey 
A handle to the registry key to read the value from. This could also be one of the following flags identifying one of the 
predefined registry base keys. The flags have identical names to the registry base keys they specify. 
HKEY_CLASSES_ROOT 
HKEY_CURRENT_CONFIG 
HKEY_CURRENT_USER 
HKEY_DYN_DATA (Windows 95, 98 only) 
HKEY_LOCAL_MACHINE 
HKEY_PERFORMANCE_DATA (Windows NT, 2000 only) 
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HKEY_USERS 
lpValueName 

The name of the value to read. 
Reserved 

Reserved. Set to 0. 


lpType 


Receives one of the following flags identifying the data type of the data being read: 


REG_BINARY 
A non-text sequence of bytes. 
REG_DWORD 


Same as REG_DWORD_LITTLE_ENDIAN. 


REG_DWORD_BIG_ENDIAN 


A 32-bit integer stored in big-endian format. This is the opposite of the way Intel-based computers normally 
store numbers -- the byte order is reversed. 


REG_DWORD_LITTLE_ENDIAN 


A 32-bit integer stored in little-endian format. This is the way Intel-based computers store numbers. 


REG_EXPAND_SZ 


A null-terminated string which contains unexpanded environment variables. 


REG_LINK 
A Unicode symbolic link. 
REG_MULTI_SZ 


A series of strings, each separated by a null character and the entire set terminated by a two null characters. 


REG_NONE 
No data type. 
REG_RESOURCE_LIST 
A list of resources in the resource map. 
REG_SZ 
A string terminated by a null character. 
lpData 


Variable, array, or some other object that receives the information read from the registry. 


lpcbData 


Set this to the length in bytes of whatever was passed as /pData to receive the data read from the registry. This 
parameter also receives the length in bytes of the data actually read from the registry. 


Constant Definitions 








































































































































































































Const HKEY CLASSES ROOT = &H80000000 
Const HKEY_CURRENT_CONFIG = &H80000005 
Const KEY _CURRENT_USER = &H80000001 
Const HKEY_DYN_DATA = &H80000006 

Const HKEY LOCAL MACHINE = &H80000002 
Const HKEY PERFORMANCE DATA = &H80000004 
Const HKEY_USERS = &H80000003 

Const REG_BINARY = 

Const REG _DWORD = 4 

Const REG _DWORD_BIG_ENDIAN = 5 

Const REG _DWORD_LITTLE _ENDIAN = 4 
Const REG _EXPAND_SZ = 2 

Const REG_LINK = 6 

Const REG _MULTI_SZ 7 

Const REG_NONE = 0 
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Const REG RESOURCE_LIST = 8 
Const REG _SZ = 1 























Example 


Open the registry key HKEY_CURRENT_USER\Software\MyCorp\MyProgram\Config and read the value named "username" 
stored in it. The example given for the RegSetValueEx function creates this key and sets the value appropriately. The example 





runs when button Command 1 is pressed. To run this example, you need to place a command button named Command 1 inside a 
form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function RegOpenKeyEx Lib "advapi32.dll" Alias "RegOpenKeyExA" (ByVal 


























hKey As Long, ByVal lpSubKey As String, ByVal ulOptions As Long, ByVal 
samDesired _ 
As Long, phkResult As Long) As Long 
Public Declare Function RegQueryValueEx Lib "advapi32.dll1" Alias "RegQueryValueExA" _ 
(ByVal hKey As Long, ByVal lpValueName As String, ByVal lpReserved As Long, 
lpType As Long, lpData As Any, lpcbData As Long) As Long 
Public Declare Function RegCloseKey Lib "advapi32.dll" (ByVal hKey As Long) As Long 
Public Const HKEY_CURRENT_USER = &H80000001 
Public Const KEY_READ &H20019 
Public Const REG _ SZ = 

























































































' *** Place the following code inside the form window. *** 








Private Sub Commandl1_Click () 























Dim hKey As Long ' receives a handle to the newly created or opened registry 
key 

Dim subkey As String ' name of the subkey to open 

Dim stringbuffer As String ' receives data read from the registry 

Dim datatype As Long ' receives data type of read value 

Dim slength As Long ' receives length of returned data 

Dim retval As Long ' return value 

' Set the name of the new key and the default security settings 








subkey = "Software\MyCorp\MyProgram\Config" 





' Create or open the registry key 

retval = RegOpenKeyEx (HKEY_CURRENT_USER, subkey, 0, KEY_READ, hKey) 
If retval <> 0 Then 
Debug.Print "ERROR: Unable to open registry key!" 
Exit Sub 



























































End If 














' Make room in the buffer to receive the incoming data. 
stringbuffer = Space(255) 
slength = 255 
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' Read the "username" value from the registry key. 




















retval = RegQueryValueEx(hKey, "username", 0, datatype, ByVal stringbuffer, 


slength) 
' Only attempt 


If datatype = RI 














to display the data if it is in fact a string. 


EG SZ Then 


' Remove empty space from the buffer and display the result. 



































stringbuffer = Left (stringbuffer, slength - 1) 

Debug.Print "Username: "; stringbuffer 
Else 

" Don't bother trying to read any other data types. 

Debug.Print "Data not in string format. Unable to interpret data." 
End If 








' Close the registry key. 
retval = RegCloseKey (hKey) 





End Sub 





See Also 


RegDelete Value, RegSetValueEx 





Category 


Registry 


Go back to the Function listing. 





Go back to the Reference section index. 





Last Modified: January 21, 2001 


This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 





This page is at http://www.vbapi.com/ref/r/regqueryvalueex.html 
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RegSetValueEx Function 











Declare Function RegSetValueEx Lib "advapi32.d1l1" Alias "“RegSetValueExA" (ByVal hKey 
As Long, ByVal lpValueName As String, ByVal Reserved As Long, ByVal dwType As Long, 
lpData As Any, ByVal cbhData As Long) As Long 
































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RegSetValueEx writes a value to a registry key. If the value does not already exist, it will be created. The value can be of any 
of the registry data types. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


When writing a string or a single numeric value, the /pData parameter must be prefixed by the ByVal keyword. Any other 
values (such as byte arrays) do not need the ByVal keyword. 


Parameters 


hKey 
A handle to the registry key to write the value under. This could also be one of the following flags identifying one of 
the predefined registry base keys: 
HKEY_CLASSES_ROOT 
The HKEY_CLASSES_ROOT base key. 
HKEY_CURRENT_CONFIG 
The HKEY_CURRENT_CONFIG base key. 
HKEY_CURRENT_USER 
The HKEY_CURRENT_USER base key. 
HKEY_DYN_DATA 
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Windows 95, 98: The HKEY_DYN_DATA base key. 
HKEY_LOCAL_MACHINE 

The HKEY_LOCAL_MACHINE base key. 
HKEY_PERFORMANCE_DATA 

Windows NT, 2000: The HKEY_PERFORMANCE_DATA base key. 
HKEY_USERS 

The HKEY_USERS base key. 


lpValueName 


The name of the value to set. If this is an empty string, the function writes to the unnamed default value (Windows 95: 
the default value always has the REG_SZ data type). 


Reserved 


Reserved. Set to 0. 


dwType 


One of the following flags identifying the data type of the data to write to the registry: 
REG_BINARY 
A non-text sequence of bytes. 
REG_DWORD 
Same as REG_DWORD_LITTLE_ENDIAN. 
REG_DWORD_BIG_ENDIAN 
A 32-bit integer stored in big-endian format. This is the opposite of the way Intel-based computers normally 
store numbers -- the word order is reversed. 
REG_DWORD_LITTLE_ENDIAN 
A 32-bit integer stored in little-endian format. This is the way Intel-based computers normally store numbers. 
REG_EXPAND_SZ 
A null-terminated string which contains unexpanded environment variables. 
REG_LINK 
A Unicode symbolic link. 
REG_MULTI_SZ 
A series of strings, each separated by a null character and the entire set terminated by a two null characters. 
REG_NONE 
No data type. 
REG_RESOURCE_LIST 
A list of resources in the resource map. 
REG_SZ 
A string terminated by a null character. 


lpData 


The number, string, or other data to write to the registry. 


cbData 


The size in bytes of the data being written to the registry. 


Constant Definitions 


Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 





Con 
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KEY_CLASSES_ROOT = &H80000000 

KEY_CURRENT_CONFIG = &H80000005 
KEY_CURRENT_USER = &H80000001 

KEY_DYN_DATA = &H80000006 
K 
K 
K 





















































EY_LOCAL_MACHINE = &H80000002 

EY _PERFORMANCE_DATA = &H80000004 
EY_USERS = &H80000003 
REG_BINARY = 3 







































































REG _DWORD = 4 
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Const REG DWORD_BIG_ENDIAN = 5 
Const REG _DWORD_LITTLE_ENDIAN = 4 
Const REG _EXPAND_SZ = 2 

Const REG_LINK = 6 

Const REG _ MULTI_SZ = 7 

Const REG _NONE = 0 

Const REG _RESOURCE_LIST = 8 

Const REG_SZ = 1 














Example 


' This code is licensed according to 


the terms and conditions listed here. 





" Create a key called HKEY_CURRE 
' Then create a "username" 
hregkey As Long ' receives 
secattr As SECURITY ATTRIBUT 
subkey As String ' 
neworused As Long '! 








value 
im 














im ES 








im 


im receives 1 


NT_US 
under that key and set its value to 
handle to the newly created or opened registry key 











ER\Software\MyCorp\MyProgram\Config. 
"Rimmer". 





security settings of the key 





name of the subkey to create 
if new key was created or 2 if an existing key 





= 


as 
im 


opened 
stringbuffer As String ' 
re As Long '! 


























im tval return value 











“Ss 
subkey 
secattr.nLength 

secattr.lpSecuri 
secattr.bInherit 





the nam 





(8 





Len (secattr) i 
(0) 1 
' 











tyDescriptor 
Handle True 








' Create or open the registry key 


f the new key and the def 
"Software\MyCorp\MyProgram\Config 
size of 
default security level 

the default value for this setting 





the string to put into the registry 


E 


ault security settings 








the structure 























retval = RegCreateKeyEx (HK 








hregkey, neworused) 

If retval <> 0 Then ' 
Debug.Print " 
End ' terminate the program 
End If 











' Write the string to the registry. 
the string 





' passed to the function must explicitly be passed 


"Rimmer" & vbNullChar 





stringbuffer 
the string 

retval RegSetValueEx (hregkey, 
Len(stringbuffer)) ' 











' Close the registry key 
retval RegCloseKey (hregkey) 











See Also 


EY CURRENT_USER, 


"username", 
write the string 





K 

















subkey, 0, "", 0, EY WRITE, secattr, 


error during open 
Error opening or creating registry key -- aborting." 





Note that because Visual Basic is being used, 








ByVal. 
" note how a null character must be appended to 


R] 














0; EG_SZ, ByVal stringbuffer, 
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RegDelete Value, RegQuery ValueEx 





Category 
Registry 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: September 11, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/r/regsetvalueex.html 
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ReleaseCapture Function 





Declare Function ReleaseCapture Lib "user32.d11" () As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


ReleaseCapture ends whatever mouse capture may be in effect, regardless of which window actually captured the mouse. 
Once ReleaseCapture is called, mouse messages are immediately routed back to the windows that would normally receive 
them. This function should be used as soon as a window no longer needs to capture the mouse after it had called SetCapture. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


The following example assumes that there is a picture box control, named Picturel, on the form window Form1. 


i 


This code is licensed according to the terms and conditions listed here. 


' 








Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
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Public 
Public 





Declare Function SetCapture Lib "user32.d11" (ByVal hWnd As Long) 
Declare Function ReleaseCapture Lib "user32.dll" () As Long 














Whenever the mouse moves, draw a line connecting the cursor's hot spot 
to the center of Picturel. Of course, the line will be clipped withing 














boundaries 


F 


of the picture box. To do this, Picturel captures the mouse input when 





' loads, and releases it when the user clicks the mouse. For simplicity, 


E 








picture box's methods are used for drawing the line instead of using th 








' proper API functions. 





Private 


End Sub 





Private 
Single) 


picture 


oldY), 


End Sub 





Private 


End Sub 





Sub Forml_Load() 

' Have Picturel capture mouse input. Also make sure that 
' Picturel's scale mode is set to "Pixel". 

Dim retval As Long ' return value 








retval = SetCapture (Picturel.hWnd) 
Picturel.ScaleMode = 3 











As Long 


the 





the 
e 


Sub Picturel_MouseMove (Button As Integer, Shift As Integer, X As Single, 





' 


box. 


Erase the previous line and draw a line connecting Picturel's center 
to the mouse cursor. The line will be clipped at the boundary of the 


Static oldX As Long, oldY As Long ' the previous mouse coordinates 





Erase the old line by drawing over it in the background color. 





Picturel.Line (Picturel.ScaleWidth / 2, Picturel.ScaleHeight / 2)-(ol1dx, 











Picturel.BackColor 


' Now draw the new line. 





Picturel.Line (Picturel.ScaleWidth / 2, Picturel.ScaleHeight / 2)-(X, Y) 





i 


Save the mouse coordinates -- they'll be needed next time. 
oldX = X: oldY = Y 





Sub Picturel_Click() 
' When the mouse is clicked, release the mouse capture. 
Dim retval As Long ' return value 














retval = ReleaseCapture () 


See Also 


GetCapture, SetCapture 


Category 


Mouse 
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Y 


As 


Windows API Guide: ReleaseCapture Function 


Back to the Function list. 
Back to the Reference section. 





Last Modified: May 21, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/r/releasecapture. html 
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ReleaseDC Function 





Declare Function ReleaseDC Lib "user32.d11" (ByVal hWnd As Long, ByVal hdc As Long) 
As Long 


Platforms: Win 32s, Win 95/98, Win NT 


ReleaseDC frees up the resources used when you use GetDC to get an object's device context. This function should not be 
used to destroy a device context obtained from CreateDC -- for those, use DeleteDC instead. This should be done after your 
program finishes using the device context. The function returns 0 if an error occured or a 1 if successful. 


hWnd 
The handle of the object to free the resources of. 
hdc 
The device context of the object to free the resources of. 


Example: 





' Get the device context of the desktop window. This example doesn't 
' use the DC for anything, but it could be used to copy the desktop image to another 
window. 

















Dim deskhwnd As Long ' receives handle to the desktop window 
Dim deskhdc As Long ' receives device context of the desktop window 
Dim retval As Long ' return value 


' Figure out the desktop's device context 
deskhwnd = GetDesktopWindow () ' get the desktop's handle 
deskhdc = GetDC (deskhwnd) ' get its device context 














' deskhdc could be used here to do any number of things.... 





' Release the device context to free up resources 
retval = ReleaseDC (deskhwnd, deskhdc) 


See Also: DeleteDC, GetDC 
Category: Devices 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/releasedc.html 
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RemoveDirectory Function 


Declare Function RemoveDirectory Lib "kernel32.d11" Alias "RemoveDirectoryA" 
(ByVal lpPathName As String) As Long 


Platforms: Win 32s, Win 95/98, Win NT 
RemoveDirectory deletes a directory from a disk. The function will not delete any files or subdirectories inside 
the directory. If the directory to delete is not completely empty, the function will fail. The function returns 1 if 


successful, or 0 if an error occured. 


lpPathName 
The directory to delete. The directory must be completely empty. 


Example: 


' Delete the directory C:\MyPrograms\TempData. 


Dim retval As Long ' return value 
retval = RemoveDirectory ("C:\MyPrograms\TempData") " delete the directory 
If retval = 1 Then ' success 


Debug.Print "C:\MyPrograms\TempData was successfully deleted." 
Else 

Debug.Print "Deletion failed. Make sure C:\MyPrograms\TempData is empty." 
End If 


See Also: CreateDirectory 
Category: Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/r/removedirectory.html 


http://216.26.168.92/vbapi/ref/r/removedirectory.html [9/1/2002 5:40:56 PM] 


Windows API Guide: RemoveMenu Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





RemoveMenu Function 


Declare Function RemoveMenu Lib "user32.d11" (ByVal hMenu As Long, ByVal 
uPosition As Long, ByVal uFlags As Long) As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RemoveMenu removes an item from a menu. If the item being removed is a submenu, the submenu is not actually 
destroyed by this function. Instead, the submenu is simply removed from the menu, allowing your program to use the 
submenu elsewhere. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get 
the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the menu to remove an item from. 
uPosition 
Either the menu item identifier of the item to remove, or the zero-based position of the item to remove, depending 
on the value of uFlags. 
uF lags 
One of the following flags specifying the type of information passed as uPosition: 
MF_BYCOMMAND 
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uPosition is the menu item identifier of the item to remove. 


MF_BYPOSITION 
uPosition is the zero-based index of the position of the item to remove. 


Constant Definitions 


Const MF_BYCOMMAND = &H0 
Const MF_BYPOSITION = &H400 


Example 


Remove the "Maximize" and "Minimize" options from a form window's system menu. Note that doing this will not 
remove the maximize and minimize buttons on the window's title bar, although the buttons will stop working. In a real 
program, if you wanted to remove the minimize and maximize buttons from a window, the best way would be to do so 
before creating the window. To use this example, place a command button named cmdExample on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetSystemMenu Lib "user32.d11" (ByVal hWnd As Long, ByVal 
bRevert As Long) As Long 
Public Declare Function RemoveMenu Lib "user32.dl11" (ByVal hMenu As Long, ByVal 
uPosition As Long, _ 
ByVal uFlags As Long) As Long 
Public Const MF_BYCOMMAND = &HO 
Public Const SC_MINIMIZE = &HFO20 
Public Const SC_MAXIMIZE &HFO30 
































' xxx Place the following code inside the form window. *** 


Private Sub cmdExample_Click () 
Dim hSysMenu As Long ' handle to the window's system menu 
Dim retval As Long ' return value of functions 





' Get a handle to the window's system menu. 

hSysMenu = GetSystemMenu (Me.hWnd, 0) 

' Remove the minimize and maximize options, using their item IDs. 
retval = RemoveMenu (hSysMenu, SC_MINIMIZE, MF_BYCOMMAND) 

retval = RemoveMenu (hSysMenu, SC_MAXIMIZE, MF_BYCOMMAND) 




















End Sub 


See Also 


InsertMenultem 
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Category 


Menus 


Back to the Function list. 
Back to the Reference section. 


Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/r/removemenu.html 
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RemoveProp Function 


Declare Function RemoveProp Lib "user32.dl1" Alias "RemovePropA" (ByVal 
hWnd As Long, ByVal lpString As String) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


RemoveProp removes a window property from a window. This property must have been previously set using 
the SetProp function. Your program must remove all window properties it creates before the window they are 

attached to closes. However, never remove any window properties not created by your program. Although this 
function deletes the property itself, it does not affect the data referenced by the property in any way. 


Return Value 


If an error occured, the function returns 0. If successful, the function returns a handle to the data which was 
attached to the property. The program is then responsible for deallocating this data, if necessary. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to remove one of the window properties of. 
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IpString 
The name of the window property to remove. 


Example 


This code is licensed according to the terms and conditions listed here. 


' Set the "LookupFile" property of window Forml to a string. 
' This example also shows how to remove the property. 





Dim hStr As Long, pStr As Long ' handle and pointer to the string 
Dim thevalue As String ' the string referenced by the handle 
Dim retval As Long ' return value 


' Set the value of the string (this could be anything, really). 
thevalue = "C:\Icons\default.ico" 


" Create a memory block... 
hStr = GlobalAlloc (GMEM MOVEABLE Or GMEM_ZEROINIT, Len(thevalue) ) 








...and copy the string into it. 
pstr = GlobalLock (hStr) ' get a pointer to the block 








retval = Ilstrcpy(pStr, text) ' copy the string 
retval = GlobalUnlock (hStr) ' release the pointer 











' The handle hStr now refers to a memory block holding the string. Set 
' the "LookupFile" property to this memory block. 
retval = SetProp(Forml.hWnd, "LookupFile", hStr) 





" Note how we cannot yet free the memory block since it is still in use. 





' xxx INSERT OTHER CODE (such as the GetProp example) HERE *** 








' The following code releases the "LookupFile" property and frees 
" the memory block to which it points. 

' (this code assumes the same Dims as above) 

hStr = RemoveProp(Forml.hWnd, "LookupFile") 

' The property is gone; now free the memory block. 

retval = GlobalFree (hStr) 








See Also 


SetProp 


Category 
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Window Properties 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: December 23, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/r/removeprop.html 
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RestartDialog Function 








Declare Function RestartDialog Lib "shel1l32.d11" Alias "#59" (ByVal hwndOwner As 
Long, ByVal lpstrReason As String, ByVal uFlags As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Unknown. 


The RestartDialog function is officially undocumented. 


Description & Usage 


RestartDialog prompts the user with a yes-or-no dialog box asking to either reboot, shut down, or log off the system. This 
dialog box is typically displayed at the end of an install routine, when a reboot is necessary to load altered system settings. If 
the user clicks the "Yes" button of the dialog, the reboot/shut down/log off operation is automatically begun. 

Windows NT, 2000: All strings used by this function must be Unicode. Therefore, any strings passed to the function must 


first be converted into Unicode. Likewise, any strings output by the function also must be converted from Unicode into 
ANSI. 


Return Value 


If successful, the function returns one of the following values. However, if an error occured, the function will return IDYES 
anyway. Therefore, the return value is an unreliable method of determining what the user selected. 


IDNO 

The user selected "No". 
IDYES 

The user selected "Yes". 


Visual Basic-Specific Issues 


None. 


Parameters 
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hwndOwner 
A handle to the window that is requesting the dialog box. 
IpstrReason 
Text to display inside the dialog box explaining why the reboot, shut down, or log off is necessary. Windows will 
append additional text to this message, so this string should end in one or two carriage return/line feed pairs (the 
intrinsic vbCrLf constant) or at least a space. 
uF lags 
One of the following flags specifying which operation to prompt the user about: 
EWX_LOGOFF 
Prompt the user to log off the system. The text appended to /pstrReason is as follows: "You must restart your 
computer before the new settings will take effect. (new line) Do you want to restart your computer now?" 
EWX_REBOOT 
Prompt the user to reboot the system. The text appended to /pstrReason is as follows: "You must restart your 
computer before the new settings will take effect. (new line) Do you want to restart your computer now?" 
EWX_SHUTDOWN 
Prompt the user to shut the system down. The text appended to /pstrReason is as follows: "Do you want to shut 
down now?" 


Constant Definitions 


Const IDNO = 7 

Const IDYES = 6 

Const EWX_LOGOFF = &HO 
Const EWX_SHUTDOWN = &H1 
Const EWX_REBOOT = &H2 

















Example 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


E 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function RestartDialog Lib "shell32.d11" Alias "#59" (ByVal hwndOwner 














As Long, ByVal lpstrReason As String, ByVal uFlags As Long) As Long 
Public Const EWX_REBOOT = &H2 
Public Type OSVERSTIONINFO 


£. 
































dwOSVersionInfoSize As Long 
dwMajorVersion As Long 
dwMinorVersion As Long 
dwBuildNumber As Long 
dwPlatformId As Long 
szCSDVersion As String * 128 








End Type 

Public Const VER PLATFORM WIN32_NT = 2 

Public Const VER PLATFORM WIN32 WINDOWS = 

Public Declare Function GetVersionEx Lib "kernel32.d1l1" Alias "GetVersionExA" _ 
(lpVersionInformation As OSVERSTIONINFO) As Long 
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' Prompt the user to reboot the computer. If he says "Yes", the function will 


' automatically reboot the system. There's nothing much to it! 
Private Sub Command1_Click () 








Dim s As String ' the string to display in the dialog 
Dim ovi As OSVERSTIONINFO ' version of the OS 
Dim retval As Long ' return value 








_ 


' Display the following message in the dialog, in front of the text that 





' Windows will automatically place there. 
s = "The install routine has made some changes to your computer. 








' Tf this is Windows NT or 2000, convert the string to Unicode. 
ovi.dwOSVersionInfoSize = Len (ovi) 
retval = GetVersionEx(ovi) 
If ovi.dwPlatformId = VER _PLATFORM WIN32_NT Then 
s = StrConv(s, vbUnicode) 




















End If 


' Prompt the user. 
retval = RestartDialog(Forml.hWnd, s, EWX_RESTART) 
End Sub 


See Also 


ExitWindowsDialog 





Category 
Shell 


Back to the Function list. 
Back to the Reference section. 








Last Modified: July 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/restartdialog.html 
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RoundRect Function 


Declare Function RoundRect Lib "gdi32.dll1" (ByVal hdc As Long, ByVal nLeftRect As 
Long, ByVal nTopRect As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long, 
ByVal nWidth As Long, ByVal nHeight As Long) As Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


RoundRect draws a rectangle with rounded corners on a device. The rounded rectangle is drawn in the device's current and is 
filled using its current brush. The first two (x,y) coordinate pairs specified are the upper-left and lower-right corners of a 
comparable square-cornered rectangle. The third pair specifies the width and height of the rounded corner to use. 


Return Value 


If an error occurs, the function returns 0 (Windows NT, 2000: use GetLastError to get the error code). If successful, the 
function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 

A handle to the device context of the device to draw on. 
nLeftRect 

The x-coordinate of the upper-left corner of the corresponding square-edged rectangle. 
nTopRect 

The y-coordinate of the upper-left corner of the corresponding square-edged rectangle. 
nRightRect 

The x-coordinate of the lower-right corner of the corresponding square-edged rectangle. 
nBottomRect 
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The y-coordinate of the lower-right corner of the corresponding square-edged rectangle. 


nWidth 


The width of each rounded corner. 


nHeight 


The height of each rounded corner. 


Example 


' This code is licensed according to the tern 





' Declarations and such needed 
(declarations) 
Declare Function RoundRect Lib "gdi32.dll1" ( 


' (Copy them to the 
Public 





As Long, ByVal 











As Long, ByVal 
Public Declare Function 








nTopRect As Long, 


nWidth As Long, 
SelectObject Lib 





for the example: 
section of a mod 








ns and conditions listed here. 


ule.) 
ByVal 


hdc As Long, ByVal nL 














"gdi32.d1l1" 





hObject _ 
As Long) As Lon 
Declare Function 


g 





Public 


ByVal nRightRect As Long, 


ByVal nHeight As Long) 
ByVal hdc As Long, 


( 


GetStockObject Lib "gdi32.d11" 





Bott 





ByVal n 





As Long 








ByVal 








(ByVal niIndex As Long) 











WHITE PEN 


LTGRAY_BRU 


6 








Public Const 
Public Const 

















SH 





' Draw a white rounded rectangle on window Formi 
and a lower-right corner of 


" corner of (25,30) 











1 




















with an upper-left 
(100,50). 


Give the rounded 


" corners a width of 10 and a height of 5. Fi the shape with light gray. 
Dim hPen As Long ' handle to the pen to use to draw the shape 

Dim hBrush As Long ' handle to the brush to use to draw the shape 

Dim hOldPen As Long ' handle to Forml's previous pen 

Dim hOldBrush As Long ' handle to Forml's previous brush 

Dim retval As Long ' return value 











' Get handles to the appropriate stock pen and brush. 








hPen = GetStockObject (WH 








TE_ 


È 





EN) 











hBrush 


" Select 
holdPen 


holdBrush 





GetStockObject 
the pen and br 








ush 














SelectObject (Forml. 
SelectObject (Forml.hDC, hBrush) 


(LTGRAY_] 


E 





' Draw the rounded rectangle. 





retval 





retval 














retval 





See Also 


Rectangle 


SelectObject (Form1 


RoundRect (Form1.hDC, 
' Restore Forml's previous pen and br 
SelectObject (Forml. 


h 
wh 


for 
h 


BRUSH) 


use by Forml. 
DC, hPen) 














25, 30, 100, 50, 10, 5) 


ush selections. 


DC, hOldPen) 
DC, hOldBrush) 
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eftRect 








omRect 


As Long 


Windows API Guide: RoundRect Function 
Category 
Filled Shapes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: April 16, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/r/roundrect.html 
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SelectObject Function 


Declare Function SelectObject Lib "gdi32.dl11" (ByVal hdc As Long, ByVal hObject 
As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SelectObject selects a given object for use on a device. Possible objects to use with this function include bitmaps, 
brushes, fonts, pens, and regions. Once selected, this object will be used by the device whenever necessary. (For 
example, the selected brush will be used whenever the device needs to perform a fill.) The function returns a handle to 
the object previously selected by the device to do that task (e.g., the old brush). The program should re-select the old 
object when it is finished using it in order to preserve the device's default objects (see the example for a demonstration 
of this). 


hdc 
A device context to the device to select an object for. 
hObject 
A handle to the bitmap, brush, font, pen, or region to select for the device. 


Example: 


' Draw a rectangle with corners (10,20) and (175,100) 





' on window Forml. Use a solid yellow brush to fill the rectangle. 

Dim hbrush As Long ' receives handle to the solid yellow brush 

Dim holdbrush As Long ' receives handle to Forml's default brush 

Dim retval As Long ' return value 

hbrush = CreateSolidBrush(RGB(255, 255, 0)) ' create a solid yellow brush 

' Save Forml's default brush so we can restore it after the program is finished 
holdbrush = SelectObject (Forml.hDC, hbrush) " select the brush 


' Draw the rectangle filled using the solid yellow brush 

retval = Rectangle (Forml.hDC, 10, 20, 175, 100) 

" Restore Forml's previous brush before destroying the created one 
retval = SelectObject (Form1l.hDC, holdbrush) " select old brush 
retval = DeleteObject (hbrush) ' destroy the solid yellow brush 





Category: Devices 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/selectobject.html 
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send Function 








Declare Function send Lib "wsock32.d1ll1" (ByVal s As Long, buf As Any, ByVal length As 
Long, ByVal flags As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


send sends data to a network host via a connected socket. The socket must have already been connected to another computer 
via connect. The Winsock implementation automatically assembles the data into whatever packets, datagrams, or other units 
that are transported via the protocol being used. 


Return Value 


If successful, the function returns the number of bytes successfully sent through the socket (although the network host may not 
necessarily have received them). If an error occured, the function returns SOCKET_ERROR (use WSAGetLastError to get the 
error code). 


Visual Basic-Specific Issues 


If specifying a string for buf, the ByVal keyword must be placed in front of it. See the example for a demonstration. 


Parameters 


S 
A descriptor of the connected socket to send the data through. 
buf 
The data to send to the network host. 
length 
The size in bytes of the data passed as buf. 
flags 
A combination of the following flags specifying additional options: 
MSG_DONTROUTE 
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Do not subject the data to routing. The Winsock implementation may choose to ignore this option if specified. 
MSG_OOB 
Send out-of-band data only. 


Constant Definitions 














Const SOCKET ERROR = -1 
Const MSG _DONTROUTE = &H4 
Const MSG_OOB = &H1 




















Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 
HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To use this example, place a command button 
named cmdDownload on a form window. 





Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 


called at the end no matter what happens, the GoTo skip down to the end if an unrecoverable error occurs. If VB had better 
exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.d1ll1" (ByVal wVersionRequested As 
Integer, lpWSAData _ 
As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d1l1" () As Long 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 

































































h_addr_list As Long 
End Type 
Public Const AF_INET = 2 
Public Declare Function gethostbyname Lib "wsock32.dl11" (ByVal name As String) As 
Long 
Public Declare Function htons Lib "wsock32.dll1" (ByVal hostshort As Integer) As 
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Integer 
Public 
As Long, 





Public Const 


Declare Function socket Lib 











Public Type SOCKAD 


End Type 
Public 











Public 
length 


Public 
length 





Public 
Public 
As Any, 











ByVal _ 
protocol As Long) As Long 
SOCK_STREAM = 1 
DR 
sin_family As Integer 





Sin_port As Integer 
sin_addr As Long 
Sin_zero As String * 8 








source _ 
As Any, 


Declare Function connect Lib 


As Long, 
ByVal flags As Long) 
Declare Function recv Lib 
As Long, 
ByVal flags As Long) 
Declare F 
Declare S 


ByVal namelen _ 
As Long) 
Declare Function send Lib 


As Long 
"wsock32.d11" 


"wsock32.dl1l1" ( 


"wsock32.dll" ( 











ByVal af As Long, 





ByVal s As Long, 





(ByVal s As Long, buf As Any, 





As Long 
"wsock32.dl11" 
As Long 

unction closesocket Lib 








ByVal Length As Long) 


' A useful API macro. 


Public Func 
MAKEWORD 


2)) 





' *** Place the following code inside the 


Private Sub 











im 
im 
im 
im 


im 





tion MAKEWORD ( 
Val ("& 














ByVal bLow As 
H" 


Byte, 
& Right ("00" 











End Function 





cmdDownload_Click () 

wsockinfo As WSADATA ' 
sock As Long ' 
retval As Long d 











"wsock32.dl1" ( 
ub CopyMemory Lib "kernel32.dll1" Alias 


form window. 





(ByVal s As Long, buf As Any, 





ByVal s As Long) 





"RtlMoveMemory" ( 





ByVal bHigh As Byte) As Integer 
& Hex(bHigh), 2) & Right ("00" 
kkk 


info about Winsock 
descriptor of the socket to use 
generic return value 





n pHostinfo As Long : 
hostinfo As HOSTENT d 
n pIPAddress As Long i 
ipAddress As Long , 


sockinfo As SOCKADDR '! 






































Initialize a Winsock session. 
retval 








WSAStartup (MAKEWORD (2, 2), 





If retval <> 0 Then 





Debug.Print 
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from server 


buffer As String ' communicat 
reply As String ' reply 
bytesleft As Long ' number of 
headerline As String ' line of 


pointer to info about the server 
info about the server 

pointer to server's IP address 
server's IP address 

info about 


the socket 


ions buffer 








bytes left to read of 


HTTP response header 


wsockinfo) 


"Unable to initialize Winsock!" 


ByVal prototype 








name As SOCKADDR 


DR, 





ByVal 





ByVal 


As Long 


Destination 


& Hex (bLow), 


response body 
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ra) 


xit Sub 





Get the IP address 





End If 
T 
pHostin 
I 














End If 











fo = gethostb 





of the server to connect to. 
yname ("www.vbapi.com") 








f pHostinfo = 0 The 





Debug.Print 
GoTo Cleanup 





n 
"Unable to resolve host!" 








CopyMemory hostinfo, 
If hostinfo.h_addrty 





End If 








Debug.Print 
GoTo Cleanup 





ByVal pHostinfo, Len(hostinfo) 
pe <> AF_INET Then 











"Couldn't get IP address of www.vbapi.com!" 





CopyMemory plIPAddress, ByVal hostinfo.h_addr_list, 4 





CopyMemory ipAddress, ByVal plPAddress, 4 


Creat 


sock = 
If sock 








End If 


socket (AF_INE 


e a socket to 





= &HFFFFFFFF 
Debug.Print 
GoTo Cleanup 











use for the TCP/IP connection. 
T, SOCK_STREAM, 0) 

Then 

"Unable to create socket!" 





Make a connection to the server. 
With sockinfo 


retval 


' Use the IP 
.-Sin_family 
" Connect to 
-Sin_port = 
' IP address 
.-Sin_addr = 
' Dummy data 
.Sin_zero = 











End With 
Debug.Print "Attempt 





= connect (soc 


If retval <> 0 Then 





End If 








i 


buffer = 


Send 


retval 





Read 
(i.e. 





Debug.Print 
GoTo Cleanup 


an HTTP reque 
"GET / HTTP 





protocol family. 

= AF_INET 

port 80 (the typical HTTP port). 
htons (80) 

of the server to connect to. 
ipAddress 
that isn't used. 
String(8, vbNullChar) 








ing to connect...." 
k, sockinfo, Len(sockinfo) ) 


"Unable to connect!" 


st to GET the document /index.html. 
/1.1" & vbCrLf & _ 





"Host: www.vbapi.com" & vbCrLf & _ 
Winsock-Example-Program" & vbCrLf & vbCrLf 


"User-Agent: 
= send(sock, 


Debug.Print "Sent re 





from the sock 
, until the c 


reply = ww 
buffer 


= Space (1024) 

















ByVal buffer, Len(buffer), 0) 
quest. Waiting for reply..." 





et until the entire HTTP response header is received. 








onnection times out or a double Cr-Lf 








' read in 1 KB chunks 
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pair is received) 
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Do 

















retval = recv(sock, ByVal buffer, Len(buffer), 0) 
reply = reply & Left (buffer, retval) 


Loop Until retval = 0 Or InStr (reply, vbCrLf & vbCrLf) <> 0 











' Parse the header to see how many more bytes we need to read. 





























Do 
headerline = Left (reply, InStr(reply, vbCrLf) - 1) 
If LCase (Left (headerline, 16)) = "content-length: " Then 
bytesleft = Val (Right (headerline, Len(headerline) - 16)) 
End If 
reply = Right (reply, Len(reply) - Len(headerline) - 2) 
Loop While bytesleft = 0 Or Left(reply, 2) = vbCrLf 





' Trim the rest of the header out of the reply. 
reply = Right (reply, Len(reply) - InStr(reply, vbCrLf & vbCrui 
bytesleft = bytesleft - Len(reply) 








Fh 
<~ 
| 
Ww 
< 











' Read the rest of the content of the response. 
Do Until bytesleft = 0 Or retval = 0 












































retval = recv (sock, ByVal buffer, Len (buffer), 0) 
reply = reply & Left (buffer, retval) 
bytesleft bytesleft - retval 
Loop 





' Print the document that was received. 
Debug.Print "Document Retrieved!" 

Debug.Print 
Debug.Print reply 




















Cleanup: 
' Closes the socket, ends the Winsock session. 
retval = closesocket (sock) 
retval = WSACleanup () 

End Sub 





See Also 


recy 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
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Sendinput Function 











Declare Function SendInput Lib "user32.d11" (ByVal nInputs As Long, pInputs As 
INPUT TYPE, ByVal cbhSize As Long) As Long 

















Platforms 


Windows 95: Not Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 with Service Pack 3 (SP3) or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


SendInput synthesizes a series of keyboard, mouse, or other hardware inputs and adds them the input stream. The events 
generated by the function are not intersperced with any other input messages, user-created or otherwise. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
number of input events which were successfully added to the input stream. 


Visual Basic-Specific Issues 


None. 


Parameters 


ninputs 
The number of elements in the array passed as p/nputs. 
pInputs 
An array holding information about each input event to insert into the input stream. Each element corresponds to a 
single input event. 
cbSize 
The size in bytes of a single INPUT_TYPE structure (not the total size of the array passed as pInputs). 


Example 
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Synthesize the user typing the letter P followed by clicking the right mouse button. Note how the information for each 
individual event is placed in its associated structure before copying it into the input array. This example runs when the user 
clicks button Command1. So, to run this example, you must first place a command button named Command 1 on a form 


window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to 
Public Type MOUS! 


dx As 
dy As 
mousel 











End Type 


Public Const 
Public Const 
Public Type KEYBDINPU 


the 





(declarations) 


KINPUT 


Long 
Long 


Data As Long 
dwFlags As Long 
time As Long 

dwExtraInfo As Long 








MOUSE 





EVENTF_RI 





TDOWN = 








MOUSE 














EVENTF_RI 














wVk As Integer 
wScan As Integer 
dwFlags As Long 
time As Long 
dwExtraInfo As Long 








End Type 


Public Const 
Public Const 
Public Type INPUT TYP! 





VK_P = & 


I 


H50 




















TUP = 


&H8 


&H10 


section of a module.) 


' using vbKeyP instead would also work 














KEYEVENTF_KE 





dwType As Long 


xi (0 To 23) 





End Type 
Public Const 
Public Const 
Public 
INPUT TYPE, 











As 





m 
D 





Byte 


YUP = 


&H2 
































INPUT_KEY 
INPUT_MOUSE 
Declare Function SendInput Lib "user32.dl1l1l" (1 





BOARD = 1 
= 0 














ByVal nInputs As Long, 


pInputs As 





ByVal cbSize As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.dll" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
KK* 


' *** Place the following code inside the 


Private Sub 
Dim 
Dim 





Dim 


' Load the information needed to imitate 





Command1 
inputevent 


mouseeventl 


With keyevent 


.WVk = 


ts (0 





t AS 


VK 


-wScan = 


—Claék.() 


To 3) 











keyevent As KEYBDINPUT 











P ' 


(0) i 


AS INPUT TYPE 





form 





Di 


the P key 
not needed 
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window. 


holds 


information about each event 





temporaril 





ly hold keyboard input info 





temporaril 


ly hold mouse input info 


pressing the P key. 
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.dwFlags 
. time 
. dw] 


0 








ExtrarIni 





0 


O 


0 


' press the key down 


' use the default 
" not needed 


End With 

' Copy the structure into the inp 
inputevents (0) .dwType INPUT_KEY 
CopyMemory inputevents(0).xi(0), 





ut array's buffer. 
BOARD 
keyevent, 

















Len (keyevent) 


' Do the same as above, but for releasing the P key. 



































With keyevent 
.wVk = VK_P ' the P key 
-wScan = 0 ' not needed 
-dwFlags = KEYEVENTF_KEYUP ' release the key 
.time = 0 ' use the default 
.dwExtraInfo = 0 ' not needed 

End With 

inputevents(1).dwType = INPUT_KEYBOARD 














CopyMemory inputevents(1).xi(0), keyevent, Len(keyevent) 
































' Load the information needed to imitate pressing the right mouse button. 
With mouseevent 

.dx = 0 ' no horizontal movement 

.dy = 0 " no vertical movement 

-mouseData = 0 " not needed 

.dwFlags = MOUSEEVENTF_RIGHTDOWN ' right button down 

.time = 0 ' use the default 

-dwExtraInfo = 0 " not needed 





End With 
' Copy the structure into the input array's buffer. 
inputevents (2) .dwType INPUT_MOUSE 
CopyMemory inputevents(2).xi(0), mouseevent, 








Len (mouseevent) 





' Do the same as above, but for releasing the right mouse button. 





End Sub 





























With mouseevent 
mouseevent.dx = 0 
mouseevent.dy = 0 
mouseevent .mouseDa 
mouseevent.dwFlags 
mouseevent.time = 
mouseevent.dw 

End With 

' Copy the structure in 

inputevents(3).dwType = 





ta 


0 


ExtraiInfo 


0 


MOUSEE 


CopyMemory inputevents(3).xi(0), 





' Now that all 
' into the array, 





SendInput 4, 


See Also 


inputevents (0), 


" no horizontal movement 


" no ver 


tical movement 


" not needed 




















EEVENTF_RIGHTUP ' 
' use the default 
0 " not needed 





to the input array's buffer. 
INPUT_MOUSE 
mouseevent, 


Len (mouseevent) 


the information for the four input events has been placed 
finally send it into the input stream. 


Len (inputevents (0) ) 
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right button up 
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keybd_event, mouse_event 


Category 


Input (General) 





Go back to the Function listing. 
Go back to the Reference section index. 
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SendMessage Function 








Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd As 
Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SendMessage sends a message to a window. Specifically, the function calls that window's procedure to handle to message. 
This function does not return until the window has completed processing the message. 


Return Value 


The function returns the return value of the message which was sent. 


Visual Basic-Specific Issues 


Whenever passing a string or a Long integer as wParam or lParam, the ByVal keyword must appear in front of the 
parameter. ByVal is not needed if a structure or a pointer is being passed. Additionally, if a literal number (i.e., one that is not 
stored in a variable) is passed, it must be encased in the CLng() Visual Basic function to force its data type to Long. See the 
example for a demonstration of ByVal usage. 


Parameters 


hWnd 
A handle to the window to send the message to. If this is HWND_BROADCAST, the message is sent to all open top- 
level windows. 
Msg 
The identifier of the message to send. 
wParam 
Additional message-specific data. 
lParam 
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Additional message-specific data. 


Constant Definitions 


Const HWND_BROADCAST = &HFFFF 


Example 


This code is licensed according to the terms and conditions listed here. 





Open the Browse for Folder dialog box and display both the display name and 
the actual name of the folder (if it is not a virtual folder). Although any 
folders under My Computer can be selected, have the directory 

' C:\StartHere selected by default. 











' *** Place the following code in a module. *** 





' This function compensates for the fact that the AddressOf operator 
' can only be used in a function call. It returns the parameter 
passed to it. 
Public Function DummyFunc (ByVal param As Long) As Long 
DummyFunc = param 

End Function 























This function is the callback function for the dialog box. It sets 
' the selected folder to C:\StartHere when the box is initialized. 
Public Function BrowseCallbackProc(ByVal hwnd As Long, ByVal uMsg As Long, ByVal 
lParam As Long, ByVal lpData As Long) As Long 

Dim pathstring As String ' name of path to set by default 

Dim retval As Long ' return value 


























' If the BFFM_INITIALIZED message is received, set th 
' default selection to C:\StartHere. 
Select Case uMsg 
Case BFFM_INITIALIZED 

pathstring = "C:\StartHere" " the path to make the default selection 

' Send a message to the dialog box telling it to select this path. 

' Note the use of ByVal and the CLng function here. 

retval = SendMessage (hwnd, BFFM_SETSELECTION, ByVal CLng(1), ByVal pathstring) 
End Select 
BrowseCallbackProc = 0 ' the function should always return 0 

End Function 
































' *** Place the following code where you want to open the *** 
' *** Browse for Folder dialog box. *** 

Dim bi As BROWSEINFO ' structure passed to the function 

Dim pidl As Long ' PIDL to the user's selection 


Dim physpath As String ' string used to temporarily hold the physical path 
Dim retval As Long ' return value 
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' Initialize the structure to be passed to the function. 

bi.hwndOwner = Forml.hWnd ' window Forml is the owner of the dialog box 
' Specify the My Computer virtual folder as the root 
retval = SHGetSpecialFolderLocation(Forml.hWnd, CSIDL_DRIVES, bi.pidlRoot) 
' Make room in the buffer to get the [virtual] folder's display name 
bi.pszDisplayName = Space (260) 

bi.lpszTitle = "Please choose a folder." ' Message displayed to the user 
bi.ulFlags = 0 ' no flags are needed her 

' Identify the callback function to use for the dialog box. Note 

' how our DummyFunc is needed because AddressOf only works 

' inside a function call. 

bi.lpfn = DummyFunc (AddressOf BrowseCallbackProc) 
























































bi.lParam = 0 ' the callback function here doesn't need this 
bi.iImage = 0 ' this will be set by the function 








" Open the Browse for Folder dialog box. 
pidl = SHBrowseForFolder (bi) 
' Tf the user selected something, display its display name 
' and its physical location on the system. 
If pidl <> 0 Then 
' Remove th mpty space from the display name variable. 
bi.pszDisplayName = Left (bi.pszDisplayName, InStr(bi.pszDisplayName, vbNullChar) - 
1) 
Debug.Print "The user selected: "; bi.pszDisplayName 
' If the folder is not a virtual folder, display its physical location. 
physpath = Space (260) ' make room in the buffer 
retval = SHGetPathFromIDList(pidl, physpath) 










































































If retval = 0 Then 
Debug.Print "Physical Location: (virtual folder)" 
Else 
' Remove th mpty space and display the result. 
physpath = Left (physpath, InStr(physpath, vbNullChar) - 1) 
Debug.Print "Physical Location: "; physpath 
End If 


' Free the pidl returned by the function. 
CoTaskMemFree pidl 
End If 





' Whether successful or not, free the PIDL which was used to 
' identify the My Computer virtual folder. 
CoTaskMemFree bi.pidlRoot 











Category 


Messages 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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2000 
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SetActiveWindow Function 


Declare Function SetActiveWindow Lib "user32.d1l1" (ByVal hwnd As Long) As Long 





Platforms: Win 32s, Win 95/98, Win NT 


SetActiveWindow makes a given window the active window for the program, giving it the focus. This window only 
becomes the foreground window if the application which owns it is the currently active program. This function can only be 
used on windows which the program owns. This function should be used carefully, since the user normally does not expect 
the active window to change unexpectedly. The function returns 1 if successful, or 0 if an error occured. 


hwnd 
A handle to the window to set as the active window. 


Example: 


' Make the window Forml the active window for the program. Note that 

' this function will not make the window the foreground window if the user is 
currently 

' working with a separate program. 

Dim retval As Long ' return value 











retval = SetActiveWindow (Form1.hWnd) ' set Forml as the application's active window 


See Also: GetActiveWindow, SetForegroundWindow 
Category: Windows 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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SetArcDirection Function 


Declare Function SetArcDirection Lib "gdi32.d11" (ByVal hdc As Long, ByVal 
ArcDirection As Long) As Long 




















Platforms: Win 32s, Win 95/98, Win NT 


SetArcDirection sets the direction that arcs are drawn in on a graphics-capable device. Arcs can be drawn either clockwise or 
counterclockwise from the starting point to the ending point. Although Win 95/98 implements this function, that platform 
ignores the setting specified and always draws arcs counterclockwise! The function returns 1 if successful, or O if an error 
occured. 


hdc 
The device context of the device to set the arc-drawing direction of. 
ArcDirection 
Exactly one of the following flags specifying which direction to draw arcs in: 
AD_CLOCKWISE = 2 
Draw arcs clockwise from the starting point to the ending point. 
AD_COUNTERCLOCKWISE = 1 
Draw arcs counterclockwise from the starting point to the ending point. 


Example: 














' Draw the arc that forms the top half of an ellipse. The ellipse 

' is centered at (100, 100), has a width of 200, and has a height of 100. The arc is 
drawn 

' in red on the window Forml. 


























Dim retval As Long ' return value 

Forml.ForeColor = RGB(255, 0, 0) ' set the drawing color to red 

retval = SetArcDirection (Forml.hDC, AD COUNTERCLOCKWISE) ' draw the arc 
counterclockwise 

' The ellipse is determined by the bounding rectangle (0,50)-(200,150). 





' The ray to (200, 100) is due right; the ray to (0, 100) is due left. 
retval = Arc(Forml.hDC, 0, 50, 200, 150, 200, 100, 0, 100) 





See Also: AngleArc, Arc, ArcTo, GetArcDirection 
Category: Lines & Curves 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 
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shop.com | 
SetBrushOrgEx Function 
Declare Function SetBrushOrgEx Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal nXOrg As 








Long, ByVal nYOrg As Long, lppt As POINT TYPE) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


SetBrushOrgEx sets the origin point for using a brush on a given device. Note that this function only takes effect on the 
next brush the device selects -- the currently selected brush in unaffected! The brush origin point determines the offset of 
the 8x8 block used to fill in areas (the brush). For example, an origin point of (2,3) would shift the fill pattern 2 pixels to 
the right and 3 pixels downward. The old brush origin point is put into the variable passed as /ppt. The function returns 1 if 
successful, or 0 if an error occured. 


hdc 

A device context to the device to set the brush origin point of. 
nXOrg 

The x-coordinate of the new brush origin point. This must be between 0 and 7 inclusive. 
nYOrg 

The y-coordinate of the new brush origin point. This must be between 0 and 7 inclusive. 
[ppt 

Receives the former brush origin point. 


Example: 


' Fill in rectange (10,20)-(200,150) on window Forml with a double diagonal- 
' cross hatch pattern: one in green, one in blue. After the first draw/paint, the 























brush 

' origin is adjusted to make a nice overlay effect. 

Dim hbrush As Long ' receives handle to the brushes the program creates 
Dim holdbrush As Long ' receives handle to the device's default brush 
Dim oldorg As POINT TYPE ' receives original origin point 

Dim xorg As POINT TYPE ' throw-away value 

Dim retval As Long ' return value 














' xx First, draw the rectangle using the green hatched pattern ** 

' Create the green hatched brush 

hbrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0, 255, 0O)) 

' Set the brush origin point to (0,0) and store the old value (we'll restore it 
later) 
retval = SetBrushOrgEx(Forml.hDC, 0, 0, oldorg) 

' Select the hatched brush and create the rectangle 

holdbrush = SelectObject (Forml.hDC, hbrush) ' select the brush 
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retval = Rectangle(Forml.hDC, 10, 20, 200, 150) ' make the rectangle 
' Restore the default brush temporarily and destroy the hatched brush 
retval = SelectObject (Forml.hDC, holdbrush) " restore old brush 
retval = DeleteObject (hbrush) ' delete the hatched brush 

' xx Now, redraw the rectangle using an offset blue hatched pattern ** 
' Create the blue hatched brush 

hbrush = CreateHatchBrush (HS_DIAGCROSS, RGB(0, 0, 255)) 

' Set the brush origin point to (4,4) and ignore the old value 

retval = SetBrushOrgEx(Forml.hDC, 0, 0, xorg) ' we don't care about xorg 
' Select the hatched brush and recreate the rectangle 

holdbrush = SelectObject (Forml.hDC, hbrush) ' select the brush 

retval = Rectangle(Forml.hDC, 10, 20, 200, 150) ' make the rectangle 
' Restore the default brush and destroy the hatched brush 

retval = SelectObject (Forml.hDC, holdbrush) " restore old brush 
retval = DeleteObject (hbrush) ' delete the hatched brush 

' Now, restore the device's old brush origin point 

retval = SetBrushOrgEx (Forml.hDC, oldorg.x, oldorg.y, xorg) 





See Also: GetBrushOrgEx 
Category: Brushes 








Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 
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SetCapture Function 








Declare Function SetCapture Lib "user32.dl1l1" (ByVal hWnd As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetCapture captures the mouse for the specified window. When a window captures the mouse, it receives all mouse input 
messages, including those which would otherwise be sent to other windows. Capturing the mouse input allows a window to 
keep track of all mouse actions via mouse messages, but no other windows will receive the mouse input. When the capture is 
no longer needed, the mouse capture should be ended by calling ReleaseCapture. 


Return Value 


If successful, the function returns a handle to the window that had previously captured the mouse, or zero if no window had 





captured the mouse. If an error occured, the function also returns 0. 


Visual Basic-Specific Issues 
None. 


Parameters 


hWnd 
A handle to the window to capture the mouse input. 


Example 


The following example assumes that there is a picture box control, named Picturel, on the form window Form1. 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 





' (Copy them to the (declarations) section of a module.) 


Public Declare Function SetCapture Lib "user32.dl1" 





(ByVal hWnd As Long) As Long 











Public Declare Function ReleaseCapture Lib "user32.dll" () As Long 





' Whenever the mouse moves, draw a line connecting the cursor's hot spot 
" to the center of Picturel. Of course, the line will be clipped withing the 








boundaries 





' of the picture box. To do this, Picturel captures the mouse input when the form 
' loads, and releases it when the user clicks the mouse. For simplicity, the 


Pa 





' picture box's methods are used for drawing the line instead of using the 


' proper API functions. 





Private Sub Forml_Load() 


' Have Picturel capture mouse input. Also make sure that 


' Picturel's scale mode is set to "Pixel". 
Dim retval As Long ' return value 





retval = SetCapture (Picturel.hWnd) 
Picturel.ScaleMode = 3 
End Sub 














Private Sub Picturel_MouseMove (Button As Integer, Shift As Integer, X As Single, 


Single) 


' Erase the previous line and draw a line connecting Picturel's center 
' to the mouse cursor. The line will be clipped at the boundary of the 





picture box. 





Static oldX As Long, oldY As Long ' the previous mouse coordinates 





' Erase the old line by drawing over it in 


the background color. 





Picturel.Line (Picturel.ScaleWidth / 2, Pic 











turel.ScaleHeight / 2)-(oldx, 








oldyY), 
Picturel.BackColor 
' Now draw the new line. 
Picturel.Line (Picturel.ScaleWidth / 2, Picturel.ScaleHeight / 2)-(X, Y) 
' Save the mouse coordinates -- they'll be needed next time. 
oldX = X: oldY = Y 
End Sub 





Private Sub Picturel_Click () 











' When the mouse is clicked, release the mouse capture. 





Dim retval As Long ' return value 





retval = ReleaseCapture () 
End Sub 








See Also 


GetCapture, ReleaseCapture 





Category 
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Mouse 


Back to the Function list. 





Back to the Reference section. 
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SetClassLong Function 


Declare Function SetClassLong Lib "user32.d11" Alias "SetClassLongA" (ByVal hWnd As 
Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetClassLong sets a single 32-bit value from the information about the window class to which the specified window belongs. 
This function can also set a 32-bit value within the extra memory area associated with the window class. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
previous setting of the 32-bit value which was changed. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to a window which belongs to the class to set a property of. 
nIndex 
To set a 32-bit value within the class's extra memory, set this to the zero-based offset of the first byte in the 32-bit 
block to set. Valid values are 0 to the number of bytes of extra memory minus 4, inclusive. To set a 32-bit property of 
the class, set this to one of the following flags specifying which 32-bit value to set from the window class: 
GCL_CBCLSEXTRA 
Set the size in bytes of the extra memory associated with the window class. dwNewLong 
is the new size of the block. 
GCL_CBWNDEXTRA 
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Set the size in bytes of the extra memory associated with each window belonging to the window class. 
dwNewLong is the new size of the block. 
GCL_HBRBACKGROUND 


Set the brush used to paint the backgrounds of windows belonging to the class. dwNewLong is a handle to the 





brush to use. 
GCL_HCURSOR 

Set the cursor associated with the class. dwNewLong is a handle to the cursor to use. 
GCL_HICON 

Set the icon associated with the class. dwNewLong is a handle to the icon to use. 
GCL_HICONSM 

Set the small icon associated with the class. dwNewLong is a handle to the small icon to use. 
GCL_HMODULE 


Change the module which registered the class. dwNewLong is a handle to the module to identify as the creator 


of the class. 
GCL_MENUNAME 


Set the string identifying the name of the menu resource associated with the class. dwNewLong is a pointer to 


the new string. 
GCL_STYLE 
Set the window styles associated with the class. dwNewLong is the new value. 


GCL_WNDPROC 


Set the WindowProc hook function to use as the window procedure for windows belonging to the window 


class. dwNewLong is a pointer to the function to use. 
dwNewLong 
The 32-bit value to set as something. 


Constant Definitions 


























Const GCL_CBCLSEXTRA = -20 
Const GCL_CBWNDEXTRA = -18 
Const GCL_HBRBACKGROUND = -10 
Const GCL_HCURSOR = -12 

Const GCL_HICON = -14 

Const GCL_HMODULE = -16 

Const GCL_MENUNAME = -8 

Const GCL_STYLE = -26 

Const GCL_WNDPROC = -24 
Example 


' This code is licensed according to the terms and conditions listed here. 


" Change the icon associated with whatever class window 
' Forml belongs to. 

Dim hIcon As Long ' handle to the new icon to use 

Dim retval As Long ' return value 








' The icon to use is in C:\MyApp\newicon.ico. 
hIcon = ExtractIcon(App.hInstance, "C:\MyApp\newicon.ico", 0) 





' Set this icon as the new class icon. 


http://216.26.168.92/vbapi/ref/s/setclasslong.html (2 of 3) [9/1/2002 5:42:11 PM] 


Windows API Guide: SetClassLong Function 


retval = SetClassLong(Forml.hWnd, GWL_HICON, hIcon) " set the class's icon, not the 
window's 

' Note that here we can't destroy the icon we extracted because it 

' is still in use by the class. 


See Also 


GetClassLong, SetWindowLong 


Category 


Window Classes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 28, 1999 
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SetCursor Function 


Declare Function SetCursor Lib "user32.d1ll1" (ByVal hCursor As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


SetCursor sets the image used to represent the mouse cursor. The new cursor can be any valid cursor that has either 
been created or loaded. If successful, the function returns a handle to the old cursor image. If unsuccessful, the 
function returns 0. 


hCursor 
The handle to the new cursor to use to represent the mouse pointer. 


Example: 


' Display the application starting (arrow and hourglass) Windows 











" cursor for three seconds. The cursor resource is loaded from Windows. Then 
' restore the old cursor (whatever it happens to be). 

Dim hcursor As Long ' receives handle to application starting cursor 

Dim holdcursor As Long ' receives handle to previously used cursor 

Dim retval As Long ' throw-away return value 

hcursor = LoadCursor(0, IDC_APPSTARTING) ' load Windows's application starting 
cursor 

holdcursor = SetCursor (hcursor) ' set it to the new cursor 


Sleep 3000 ' wait for 3 seconds 
retval = SetCursor (holdcursor) ' set it to the previous cursor 


See Also: GetCursor, SetSystemCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
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SetCursorPos Function 


Declare Function SetCursorPos Lib "user32.d11" (ByVal x As Long, ByVal 
y As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 
SetCursorPos sets the position of the mouse cursor. If you try to set the coordinates outside of the range 
of the display (for example, to (700,40) on a 640x480 display) or outside the confining rectangle (set by 


ClipCursor), the cursor will just go to the edge of the screen or the rectangle. The function returns 0 if an 
error occured, or 1 if successful. 


The x coordinate to move the cursor to. 


The y coordinate to move the cursor to. 
Example: 


" Move the mouse cursor to the point (100,200) on the screen 
Dim retval As Long ' return value 


retval = SetCursorPos(100, 200) " move the cursor to (100,200) 


See Also: GetCursorPos 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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SetDoubleClickTime Function 


Declare Function SetDoubleClickTime Lib "user32.dl11" (ByVal wCount As Long) 
As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetDoubleClickTime sets the maximum amount of time allowed between successive mouse clicks for 
Windows to determine it as a double click. This function alters how Windows interprets a double click, so of 
course all applications as well as Windows itself will be affected. Be careful using this function, since the user 
usually sets the double click speed via Windows's Control Panel, so he/she may not expect a change in the 
double click speed. The function returns 1 if successful, or 0 if an error occured. 


wCount 
The maximum amount of time, in milliseconds, to allow between successive clicks for Windows to 
interpret it as a double click. A value of 0 restores Windows's default double click speed of 500 
milliseconds. 


Example: 


' Set the maximum double click speed to 1 second. 
Dim retval As Long ' return value 


retval = SetDoubleClickTime (1000) " set the double click speed to 1 second 
Debug.Print "The double click speed is now 1 second (1000 milliseconds) ." 


See Also: GetDoubleClickTime 
Category: Mouse 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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SetEnvironmentVariable Function 


Declare Function SetEnvironmentVariable Lib "kernel32.d1l1" Alias 
"SetEnvironmentVariableA" (ByVal lpName As String, ByVal lpValue As 
String) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetEnvironmentVariable sets the value of one of the computer's environment variables. 


Return Value 


If successful, the function returns a nonzero value. If an error occured, the function returns zero (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


lpName 

The name of the environment variable to set. 
lpValue 

The value to give to the environment variable. 
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Example 


Change the value of the TEMP and TMP environment variables, which refer to the directory used to store 
temporary files, to "D:\Temp". This probably isn't the best way to try to change the temporary file directory, 
but remember, this is just an example. The example runs when the user clicks button Command1. Naturally, to 
use this example, you must place a command button named Command 1 on a form window. 


This code is licensed according to the terms and conditions listed here. 








Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function SetEnvironmentVariable Lib "kernel32.dll1" Alias 
"SetEnvironmentVariableA" (ByVal _ 

lpName As String, ByVal lpValue As String) As Long 





xxx Place the following code inside the form window. *** 


Private Sub Commandl1_Click() 
Dim retval As Long ' return value 





" Change the value of the TEMP and TMP environment variables. 
retval = SetEnvironmentVariable("TEMP", "D:\Temp") 
retval = SetEnvironmentVariable("TMP", "D:\Temp") 
' That's all there is to it! 
End Sub 


See Also 


GetEnvironmentVariable 





Category 


Processes & Threads 


Back to the Function list. 
Back to the Reference section. 


Last Modified: August 26, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


http://216.26.168.92/vbapi/ref/s/setenvironmentvariable.html (2 of 3) [9/1/2002 5:42:46 PM] 


Windows API Guide: SetEnvironmentVariable Function 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setenvironmentvariable.html 





http://216.26.168.92/vbapi/ref/s/setenvironmentvariable.html (3 of 3) [9/1/2002 5:42:46 PM] 


Windows API Guide: SetFileAttributes Function 


vbapi.com - part of the VB-World Network W -A ITE | C | | F F 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





SetFileAttributes Function 


Declare Function SetFileAttributes Lib "kernel32.d1l1" Alias "SetFileAttributesA" 
(ByVal lpFileName As String, ByVal dwFileAttributes As Long) As Long 














Platforms: Win 32s, Win 95/98, Win NT 


SetFileAttributes changes the attributes of a file or a directory. The four attributes you can set are archive, read-only, 


hidden, and system status -- the other attributes merely reflect unchangeable properties of the file. Any of the four can be 


on or off in any order. The function returns 0 if an error occured, or 1 if successful. 


lp FileName 
The filename or directory, including the full path, to change the attributes of. 
dwFileAttributes 
One or more of the following flags specifying the attributes to set (those that can only be set by the operating 
system are not listed here): 
FILE_ATTRIBUTE_ARCHIVE = &H20 
An archive file (which most files are). 
FILE_ATTRIBUTE_HIDDEN = &H2 
A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL = &H80 
An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY = &H1 
A read-only file. 
FILE_ATTRIBUTE_SYSTEM = &H4 
A system file, used exclusively by the operating system. 


Example: 





' Set the file C:\MyProgram\secret.dat to a hidden, read-only, 
' archive file. 

Dim fileattrs As Long ' file attributes 

Dim retval As Long ' return value 






































fileattrs = FILE_ATTRIBUTES_ARCHIVE Or FILE_ATTRIBUTES_HIDDEN Or 
FILE _ATTRIBUTES_READONLY 




















retval = SetFileAttributes ("C:\MyProgram\secret.dat", fileattrs) ' set the fil 
attributes 


See Also: GetFileAttributes 
Category: Files 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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SetFilePointer Function 








Declare Function SetFilePointer Lib "kernel32.d11" (ByVal hFile As Long, ByVal 
1DistanceToMove As Long, lpDistanceToMoveHigh As Long, ByVal dwMoveMethod As Long) As 
Long 




















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetFilePointer changes the position of the file pointer in an open file. The pointer can be moved either forwards or backwards 
relative to the beginning of the file, the current file pointer position, or the end of the file. The file pointer cannot be moved 
more than one byte past the last byte of the file (where it would point to the end of the file). 


When calculating the value for /DistanceToMove and the value to set the variable passed as [pDistanceToMoveHigh for 
negative numbers (1.e., moving the file pointer backwards), you cannot simply take the negative of the absolute value. First put 
the absolute values into those parameters. For /pDistanceToMoveHigh, perform a bitwise NOT operation on the value. For 
IDistanceToMove, perform a bitwise NOT operation followed by adding 1. See the example for a demonstration of this 
procedure, which is necessary to product a 64-bit negative number from a composite of the two dwords. 


Return Value 


If successful, the function returns the low-order dword of the new file pointer position. The high-order dword of the file pointer 
position is placed into the variable passed as [pDistanceToMoveHigh. If an error occured, the function returns -1 (use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hFile 
A handle to the open file to move the file pointer of. 
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lDistanceToMove 
The low-order dword of the 64-bit integer identifying the number of bytes to move the file pointer. For negative values, 
consult the second paragraph under Description & Usage above. 
[pDistanceToMoveHigh 
Variable that contains the high-order dword of the 64-bit integer identifying the number of bytes to move the file 
pointer. For negative values, consult the second paragraph under Description & Usage above. After the call, the 
variable receives the high-order dword of the new file pointer. 
dwMoveMethod 
One of the following flags specifying the reference point to move the file pointer from: 
FILE_BEGIN 
The beginning of the file; i.e., the very first byte of the file. 
FILE_CURRENT 
The current position of the file pointer. 
FILE_END 
The end of the file; i.e., immediately after the very last byte of the file. 


Constant Definitions 








Const FILE BEGIN = 0 
Const FILE CURRENT = 1 
Const FILE END = 2 



































Example 


Read two four-character strings from the file "C:\Test\myfile.txt": one string starting at the third byte from the beginning, and 
the other starting five bytes from the end. To use this example, place a command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function CreateFile Lib "kernel32.d11" Alias "CreateFileA" (ByVal 
lpFileName As String, _ 
ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, 
lpSecurityAttributes As Any, _ 
ByVal dwCreationDisposition As Long, ByVal dwFlagsAndAttributes As Long, 
ByVal hTemplateFile _ 

As Long) As Long 
Public Const GENERIC_READ = &H80000000 
Public Const FILE SHARE READ = &H1 
Public Const 
P 
P 
1] 







































































t OPEN_EXISTING = 3 

ublic Const FILE _ATTRIBUTE_ARCHIVE = &H20 

ublic Declare Function SetFilePointer Lib "kernel32.dll1" (ByVal hFile As Long, ByVal 
DistanceToMove _ 
As Long, lpDistanceToMoveHigh As Long, ByVal dwMoveMethod As Long) As Long 
Public Const FILE BEGIN = 0 

Public Const FILE_END = 2 

Public Declare Function ReadFile Lib "kernel32.dl1" (ByVal hFile As Long, lpBuffer As 
Any, 






































































































































ByVal nNumberOfBytesToRead As Long, lpNumberOfBytesRead As Long, lpOverlapped 
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As Any) As Long 
Public Declare Function CloseHandle Lib "kernel32.d11" (ByVal hObject As Long) As 
Long 














' *** Place the following code inside the form window. *** 








Private Sub Command1_Click () 
































































































































Dim strbuf As String * 4 ' receives four-byte string from the file 

Dim lowbyte As Long ' low dword of file pointer position 

Dim highbyte As Long ' high dword of file pointer position 

Dim numread As Long ' receives number of bytes read from file 

Dim hFile As Long ' handle of the open file 

Dim retval As Long ' return value 

' Open the fil for read-level access, if it already exists. 

hFile = CreateFile("C:\Test\myfile.txt", GENERAL READ, FILE_SHARE READ, ByVal 

CLng(0), _ 

OPEN_EXISTING, FILE ATTRIBUTE ARCHIVE, 0) 

If hFile = -1 Then 
Debug.Print "Unable to open the file -- it probably does not exist." 
Exit Sub 

End If 














' Keep in mind that, although the lpDistanceToMoveHigh parameter 

' must be passed a variable, the 1DistanceToMove parameter can be 
passed either a variable or a literal constant. For clarity, the 
following code uses a variable for 1DistanceToMove. 





























' Set the file pointer to 2 bytes after the beginning of the file -- i.e., 
the third byte position. 

lowbyte = 2 

highbyte = 0 

lowbyte = SetFilePointer(hFile, lowbyte, highbyte, FILE_BEGIN) 

' Now read four characters and display them. 

retval = ReadFile(hFile, ByVal strbuf, 4, numread, ByVal CLng(0)) 
Debug.Print "Four-character string starting at byte 3: "; strbuf 


















































' Set the file pointer to 5 bytes before the beginning of the file. Note how 
the lowbyte 

' and highbyte numbers must be manipulated to represent a negative value. 

lowbyte = (Not 5) + 1 

highbyte = Not 0 

lowbyte = SetFilePointer(hFile, lowbyte, highbyte, FILE_END) 

' Now read four characters from here and display them. 

retval = ReadFile(hFile, ByVal strbuf, 4, numread, ByVal CLng(0)) 
Debug.Print "Four-character string starting at the fifth byte from the end: 
Ts strbuf 















































" Close the file. 
retval = CloseHandle (hFile) 
End Sub 
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See Also 


ReadFile, WriteFile 





Category 


Files 


Go back to the Function listing. 
Go back to the Reference section index. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setfilepointer.html 
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SetFileTime Function 


Declare Function SetFileTime Lib "kernel32.d11" (ByVal hFile As Long, 
lpCreationTime As FILETIME, lpLastAccessTime As FILETIME, lpLastWriteTime 
As FILETIME) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetFileTime sets the creation, last-accessed, and last-modified (last written-to) dates and times associated 
with a file. All the times are in UTC time (Coordinated Universal Time, a.k.a. Greenwich Mean Time 
(GMT)), not in the system's local time. The times actually stored on the system may vary slightly from the 
times passed to the function because file times are not stored with perfect resolution (for example, seconds 
data may be ignored). 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


http://216.26.168.92/vbapi/ret/s/setfiletime.html (1 of 3) [9/1/2002 5:43:14 PM] 


Windows API Guide: SetFileTime Function 


hFile 
A handle to the opened file to set the times of. The file must have been opened with at least write-level 
access. 
lpCreationTime 
The date and time to set as the file's creation time. 
IpLastAccessTime 
The date and time to set as the file's last access time. 
lpLastWriteTime 
The date and time to set as the file's last write-to (modification) time. 


Example 


This code is licensed according to the terms and conditions listed here. 


' Set the modification time of C:\MyApp\test.txt to 











" the current system date and time. Leave the other times as they 
' were before calling the function. 

Dim hFile As Long ' handle to the opened file 

Dim ctime As FILETIME ' the time of creation 

Dim atime As FILETIME ' the time of last access 

Dim mtime As FILETIME ' the time of last modification 

Dim retval As Long ' return value 








' First, open the file C:\MyApp\test.txt for both read-level and 

' write-level access, since we need to do both. 

hFile = CreateFile("C:\MyApp\test.txt", GENERIC_READ Or GENERIC_WRITE, 
FILE SHARE READ, ByVal CLng(0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0) 
If hFile = -1 Then 


























Debug .Prink “Could not open the file successfully == aborting.” 
End ' terminate the program 
End If 





" Next, get the creation, last-access, and last-modification times. 
retval = GetFileTime(hFile, ctime, atime, mtime) 





" Get the system time (already in UTC) as a FILETIME structure. 
GetSystemTimeAsFileTime mtime 








Set the retrieved creation and access times and the new modification 
time as the file's times. 
retval = SetFileTime(hFile, ctime, atime, mtime) 





" Close the file to free up resources. 
retval = CloseHandle (hFile) 
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See Also 


GetFileTime 


Category 


Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: October 2, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/setfiletime.html 
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SetFocus Function 








Declare Function SetFocusAPI Lib "user32.dl1l" Alias "SetFocus" (ByVal hWnd As Long) 
As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetFocus gives a window the input focus. The window must be owned by the thread calling the function, however -- the 
function will not set the focus to another program's window. 


Return Value 


If successful, the function returns a handle to the window that previously had the input focus. If an error occured, the function 
returns zero (use GetLastError to get the error code). 


Visual Basic-Specific Issues 


This function behaves exactly like the SetFocus method of many VB controls. However, because this function shares its 
name with this method, it must be renamed to something like SetFocusAPI when you use it in a VB program, or else the 
compiler will give you an error. See the example for a demonstration of this. 


Parameters 


hWnd 
A handle to the window to give the input focus. 


Example 


When the form loads, immediately give button cmdGetsFocus the keyboard focus. Although an easier way to do this is 
through the button's SetFocus method, the API function is useful if you only have a handle to the window you want to give 
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the focus. To use this example, you must place a button named cmdGetsFocus on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SetFocusAPI Lib "user32.dl1" Alias "SetFocus" (ByVal hWnd As 


Long) As Long 











' *** Place the following code inside a form window. *** 


Private Sub Form_Load() 
Dim retval As Long ' return value 





' Give the input focus to cmdGetsFocus right away. 
retval = SetFocusAPI (cmdGetsFocus.hWnd) 
End Sub 


See Also 


GetFocus 


Category 


Windows 


Back to the Function list. 
Back to the Reference section. 


Last Modified: December 17, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/(?/name).html 
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SetForegroundWindow Function 


Declare Function SetForegroundWindow Lib "user32.d1ll" (ByVal hwnd As Long) As 
Long 


Platforms: Win 95/98, Win NT 


SetForegroundWindow makes the specified window the current foreground window and gives it the focus. This 
function should only be used with windows which your program owns. Of course this function should be used with 
caution, since the user usually doesn't expect the foreground window to change unexpectedly. The function tells 
Windows to somehow draw the user's attention to the window, such as by flashing its icon in the taskbar. The 
function returns 1 if successful, or 0 if an error occured. 


hwnd 
A handle to the window to set as the foreground window. 
Example: 
' Make the window Forml the current foreground window. The operating 
' system will somehow draw the user to the window. 
Dim retval As Long ' return value 
retval = SetForegroundWindow (Form1 .hWnd) ' set Forml as the foreground window 


See Also: GetForegroundWindow, SetActiveWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www. vbapi.com/ref/s/setforegroundwindow.html 
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SetKeyboardState Function 


Declare Function SetKeyboardState Lib "user32.dl1" (lpKeyState As Byte) As 
Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetKeyboardState sets the state of every key on the keyboard. Each element of the 256-element array 
identifies information about the virtual-key whose virtual-key code matches the index of the element. If the 
&H1 bit is set, that key is considered toggled. If the &H80 bit is set, the key is considered to be currently 
pressed down. The keyboard information set by this function is thread-specific; its settings do not necessarily 
change key states pertaining to the system as a whole. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpKeyState 
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A 256-element byte array which specifies the key status information for all virtual-keys. Each key is 
identified by the element corresponding with the key's virtual key code. Windows NT, 2000: In 


addition to the virtual keys, the array also sets information which distinguishes between the left and 
right Ctrl, Alt, and Shift keys, which are stored in the array at the following indices: 
VK_LSHIFT 


The 


left Shift key. 


VK_RSHIFT 


The 


right Shift key. 


VK_LCONTROL 


The 


left Ctrl key. 


VK_RCONTROL 


The 


right Ctrl key. 


VK_LMENU 


The 


left Alt key. 





VK_RMENU 


The 


right Alt key. 


Constant Definitions 


Const VK_LSHIFT = &HAO 
Const VK_RSHIFT = &HA1 
Const VK_LCONTROL = &HA2 








Const VK_RCONTROL 





&HA3 


Const VK_LMENU = &HA4 
Const VK_RMENU = &HA5 





Example 


' This code is licensed according to the terms and conditions listed here. 





' Set the toggle status for every key on the keyboard to "not 


" toggled." 





' First, get 


This change only applies to the current thread. 


Dim keystates(0 To 255) As Byte ' holds states of entire keyboard 
Dim c As Integer ' counter variable 
Dim retval As Long ' return value 





the current state of the keyboard. 


retval = GetKeyboardState (keystates (0) ) 





' Now, loop through each element and explicitly set the toggle bit to 0. 


For c = 0 To 


2595 


' Make sure the &H1 bit is not set. 
keystates (c) = keystates(c) And (Not &H1) 
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Next c 


' Finally, set this to the current keyboard state. 
retval = SetKeyboardState (keystates (0) ) 


See Also 


GetKeyboardState 


Category 


Keyboard 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: September 5, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 Go back 
to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/setkeyboardstate.html 
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SetLastError Function 


Declare Sub SetLastError Lib "kernel32.d11" (ByVal dwErrCode As Long) 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetLastError sets the API function error code for the calling thread. This error code is usually used to give a more 


detailed description of an error rather than a simple failure notification. The error code set by this function persists 
either until the next call to SetLastError or SetLastErrorEx or until another API function sets the error code from 


its operations (almost all of them call SetLastError internally). 





Return Value 


SetLastError does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwErrCode 
The error code of the error to report. If your define your own error codes for use in your program, be sure 


that bit 29 (&H20000000) in it is set. Bit 29 denotes an application-defined error code; no error codes used 
by Windows have that bit set. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Use SetLastError to test the failure condition for another 

' API function. By setting the API error code, the error handling 
' code can be run by simulating an actual error. 

Dim retval As Long ' return value 








' Get the attributes of the file C:\autoexec.bat. 
retval = GetFileAttributes("C:\autoexec.bat") 





' Now "fake" a File Not Found error by setting the returned value to 
' zero and setting the API error code to the proper value. 

' (Obviously, these two lines would be removed after testing 

" the error handler routine.) 

retval = 0 ' make it look like the function failed 

SetLastError EHRROR_FILE NOT_FOUND 











' Now try to trap for the error. 
If retval = 0 Then ' some error occured 
Select Case Err.LastDllError ' see the GetLastError page for usage of this 
Case ERROR_FILE_NOT_FOUND ' File Not Found 
Debug.Print "The specified file could not be found." 
Case Else ' ??? 
Debug.Print "An unknown and untrapped error occured." 
End Select 
Else 
Debug.Print "The function call was successful." 
End If 


























See Also 


GetLastError, SetLastErrorEx 





Category 


Errors 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Last Modified: January 6, 2000 
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SetLastErrorEx Function 


Declare Sub SetLastErrorEx Lib "kernel32.d1l1" (ByVal dwErrCode As Long, ByVal 
dwType As Long) 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetLastErrorEx sets the API function error code for the calling thread. This error code is usually used to give a 


more detailed description of an error rather than a simple failure notification. The error code set by this function 
persists either until the next call to SetLastError or SetLastErrorEx or until another API function sets the error 


code from its operations (almost all of them call SetLastError internally). 





Return Value 


SetLastError does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwErrCode 
The error code of the error to report. If your define your own error codes for use in your program, be sure 


that bit 29 (&H20000000) in it is set. Bit 29 denotes an application-defined error code; no error codes used 
by Windows have that bit set. 
dwType 
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Reserved -- set to 0. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Use SetLastErrorEx to test the failure condition for another 
' API function. By setting the API error code, the error handling 
' code can be run by simulating an actual error. 


oo 


Dim retval As Long ' return value 











' Get the attributes of the file C:\autoexec.bat. 
retval = GetFileAttributes("C:\autoexec.bat") 





' Now "fake" a File Not Found error by setting the returned value to 
' zero and setting the API error code to the proper value. 

' (Obviously, these two lines would be removed after testing 

" the error handler routine.) 

retval = 0 ' make it look like the function failed 

SetLastErrorEx ERROR_FILE NOT _FOUND 














' Now try to trap for the error. 
If retval = 0 Then ' some error occured 
Select Case Err.LastDllError ' see the GetLastError page for usage of this 
Case ERROR_FILE NOT _FOUND ' File Not Found 
Debug.Print "The specified file could not be found." 
Case Else ' ??? 
Debug.Print "An unknown and untrapped error occured." 
End Select 
Else 
Debug.Print "The function call was successful." 
End If 


























See Also 


GetLastError, SetLastError 





Category 


Errors 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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SetMenultemInfo Function 























Declare Function SetMenulItemInfo Lib "user32.d1l1" Alias "SetMenulItemInfoA" (ByVal 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As MENUITEMINFO) 
As Long 












































Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetMenultemInfo changes the attribues of an existing menu item. This function can alter almost anything about the menu 
item, including whether it is checked, enabled, or default, among other things. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0 (use GetLastError to get the error 
code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the menu that contains the item to change. 
ultem 
Identifies the menu item to change. This could be either a position or a menu item identifier, depending on fByPosition. 
JByPosition 
If this is a non-zero value, ultem indicates the item by using its zero-based position. (For example, the first item in the 
menu has a position of 0.) If this is zero, then ultem is the unique menu item identifier of the item. 
Ipmii 
Describes the changes to make to the menu item. 
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Example 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

' There's quite a few declarations for this example, but it's worth it! 

ublic Declare Function GetSystemMenu Lib "user32.d1l" (ByVal hWnd As Long, ByVal 























tg 











bRevert _ 
As Long) As Long 
ublic Declare Function GetMenulItemCount Lib "user32.dll1" (ByVal hMenu As Long) As 





AG) 








Long 
ublic Type MENUITEMINFO 
cbhSize As Long 
fMask As Long 
fType As Long 
fState As Long 
wID As Long 
hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 
cch As Long 
End Type 
Public Con 
Public Con 
Public Con 
Public Con 
P 
P 
P 
P 
( 








tg 
































[IM_STATE = &H1 
IIM_ID = &H2 
IIM_TYPE = &H10 
FT_SEPARATOR = &H800 
ublic Con FT_STRING = &HO 
ublic Con FS ENABLED = &HO 
ublic Const MFS CHECKED = &H8 
ublic Declare Function InsertMenultem Lib "user32.dll" Alias "“InsertMenuItemA" 


























c 
Te l is sis 


S 
S 
st 
si 
S 
S 







































































ByVal _ 











hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 
ublic Declare Function SetMenuItemInfo Lib "user32.dll" Alias "SetMenuItemInfoA" 
ByVal _ 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 























tg 











~ 



















































































Public Declare Function SetWindowPos Lib "user32.dll" (ByVal hWnd As Long, ByVal _ 
hWndInsertAfter As Long, ByVal x As Long, ByVal y As Long, ByVal cx As Long, 

ByVal _ 
cy As Long, ByVal wFlags As Long) As Long 

Public Const HWND_TOPMOST = -1 

Public Const HWND_NOTOPMOST = -2 

Public Const SWP_NOMOVE = &H2 

Public Const SWP_NOSIZE = &H1 




















Public Declare Function SetWindowLong Lib "user32.dll" Alias "SetWindowLongA" (ByVal 
hWnd _ 
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As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 
ublic Const GWL_WNDPROC = -4 
ublic Declare Function CallWindowProc Lib "user32.d1l1" Alias "CallWindowProcA" 
ByVal 


tg 





tg 














— 











lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 

Public Const WM SYSCOMMAND = &H112 

Public Const WM INITMENU = &H116 




















' Add an option to make window Forml "Always On Top" to the bottom of its system 




















' menu. A check mark appears next to this option when active. The menu item acts as 
a toggle. 

' Note how subclassing the window is necessary to process the two messages needed 

' to give the added system menu item its full functionality. 

' *** Place the following code in a module. *** 


Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public ontop As Boolean ' identifies if Forml is always on top or not 

















' The following function acts as Forml's window procedure to process messages. 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 









































As Long, ByVal lParam As Long) As Long 
Dim hSysMenu As Long ' handle to Forml's system menu 
Dim mii As MENUITEMINFO ' menu item information for Always On Top 
Dim retval As Long ' return value 


Select Case uMsg 

Case WM INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 




































































With mii 
' Size of the structure. 
.cbSize = Len(mii) 
' Only use what needs to be changed. 
.fMask = MIIM_ STATE 
' If Forml is now always on top, check the item. 
.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenuItemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 





Case WM SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 








top 





' setting of Forml to match. 
If wParam = 1 Then 








' Reverse the setting and make it the current one. 
ontop = Not ontop 
retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 


























HWND_NOTOPMOST), 





0, 0, 0, 0, SWP_NOMOVE Or SWP_NOSTIZI 








CI 
Sis 
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WindowProc = 0 
Else 
' Some other item was selected. Let the previous window 
procedure 
' process it. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, 
lParam) 
End If 








Case Else 
' If this is some other message, let the previous procedure handle 





it. 

WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 
End Select 
End Function 














' *** Place the following code inside Forml. *** 


' When Forml loads, add Always On Top to the system menu and set up the 























new window procedure. 
Private Sub Form_Load() 
Dim hSysMenu As Long ' handle to the system menu 
Dim count As Long ' the number of items initially on the menu 
Dim mii As MENUITEMINFO ' describes a menu item to add 
Dim retval As Long ' return value 


' Get a handle to the system menu. 
hSysMenu = GetSystemMenu(Forml.hWnd, 0) 

' See how many items are currently in it. 
count = GetMenultemCount (hSysMenu) 














' Add a separator bar and then Always On Top to the system menu. 









































With mii 
' The size of the structure. 
.cbSize = Len (mii) 
' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 
.£Type = MFT_SEPARATOR 
" It has an ID of 0. 
-wID = 0 
End With 
' Add the separator to the end of the system menu. 
retval = InsertMenultem(hSysMenu, count, 1, mii) 











' Likewise, add the Always On Top command. 
With mii 


T 


.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' This is a regular text item. 

.fType = MFT_STRING 

The option is enabled. 

-fState = MFS_ ENABLED 
' It has an ID of 1 (this identifies it in the window procedure). 
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.wID = 1 
' The text to place in the menu item. 
.dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenulItem(hSysMenu, count + 1, 1, mii) 





' Set the custom window procedure to process Forml's messages. 
ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 


End Sub 




















' Before unloading, restore the default system menu and remove the 
' custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














' Replace the previous window procedure to prevent crashing. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
' Remove the modifications made to the system menu. 
retval = GetSystemMenu(Forml.hWnd, 1) 
End Sub 


























See Also 


GetMenultemInfo 





Category 


Menus 


Back to the Function list. 
Back to the Reference section. 





Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setmenuiteminfo.html 
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SetParent Function 


Declare Function SetParent Lib "user32.dll" (ByVal hWndChild As Long, ByVal 
hWndNewParent As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetParent moves a window from having one parent window to another. If needed, the window itself moves so it can be 
"inside" its new parent. The child window can also become independent by making it a child of the desktop. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
handle to the child window's former parent window. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWndChild 
The handle of the window to change the parent of. 

hWndNewParent 
The handle of the window to become the new parent of the child window. To make the desktop the parent, pass 
0 for this parameter. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


" Move button Commandl, which is a child window, from its old 
" parent window of Forml to its new parent window of Form2. 





Dim oldhwnd As Long ' receives handle of button's former parent 
oldhwnd = SetParent (Commandl.hWnd, Form2.hWnd) " button is now in window Form2. 
See Also 


IsChild, GetParent 


Category 


Windows 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


Last Modified: August 1, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setparent.html 
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SetPixel Function 


Declare Function SetPixel Lib "gdi32.dll" (ByVal hdc As Long, ByVal X As 
Long, ByVal Y As Long, ByVal crColor As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetPixel sets the color of a single pixel on a device. Because of color matching on the device, sometimes the 
color actually used on the device may differ from the color specified by the function. The function will fail if 
the pixel specified is not visible or out of range when the function is called. 





Return Value 


If an error occured, the function returns -1 (call GetLastError to get the error code). If successful, the function 
returns the RGB value of the color which was actually used to color the pixel on the device. 


Visual Basic-Specific Issues 
None. 


Parameters 


hdc 
A handle to a device context to the device to color a pixel of. 


X 
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The x-coordinate of the pixel to color. 
Y 

The y-coordinate of the pixel to color. 
crColor 

The RGB value of the color to set the pixel to. 


Example 


This code is licensed according to the terms and conditions listed here. 
' Randomly color all the pixels in window Formi. This example 
gets the rectangle of Forml and iterates through all the points 
(pixels) inside of it. 

















Dim winrect As RECT ' rectangle of window Forml 

Dim rgbval As Long ' RGB value of the randomly selected color 
Dim x As Long, y As Long ' counters for x and y coordinates 
Dim retval As Long ' return value 





Get the rectangle of window Forml. 
retval = GetWindowRect (Forml.hWnd, winrect) 





Loop through each pixel within Forml. 
For y = 0 To winrect.bottom - winrect.top 
For x = 0 To winrect.right - winrect.left 
' Select a random color by choosing a value between 0 and 255 
inclusive for each component of the color. 
rgbval = RGB(Int (256 * Rnd), Int(256 * Rnd), Int(256 * Rnd) ) 
' Set the pixel to the color above. 
retval = SetPixel(Forml.hDC, x, y, rgbval) 
Next x 
Next y 





See Also 


GetPixel, SetPixelV 





Category 


Bitmaps 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Last Modified: September 3, 1999 
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SetPixelV Function 


Declare Function SetPixelV Lib "gdi32.dll" (ByVal hdc As Long, ByVal X As 
Long, ByVal Y As Long, ByVal crColor As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetPixelV sets the color of a single pixel on a device. Because of color matching on the device, sometimes the 
color actually used on the device may differ from the color specified by the function. The function will fail if 
the pixel specified is not visible or out of range when the function is called. This function executes slightly 
more quickly than SetPixel because this function does not need to return the actual color used by the device. 





Return Value 


If an error occured, the function returns 0 (call GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 
A handle to a device context to the device to color a pixel of. 
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X 

The x-coordinate of the pixel to color. 
Y 

The y-coordinate of the pixel to color. 
crColor 

The RGB value of the color to set the pixel to. 


Example 


This code is licensed according to the terms and conditions listed here. 
' Randomly color all the pixels in window Formi. This example 
gets the rectangle of Forml and iterates through all the points 
(pixels) inside of it. 














Dim winrect As RECT ' rectangle of window Forml 

Dim rgbval As Long ' RGB value of the randomly selected color 
Dim x As Long, y As Long ' counters for x and y coordinates 
Dim retval As Long ' return value 








Get the rectangle of window Forml. 
retval = GetWindowRect (Forml.hWnd, winrect) 





Loop through each pixel within Forml. 
For y = 0 To winrect.bottom - winrect.top 
For x = 0 To winrect.right - winrect.left 
' Select a random color by choosing a value between 0 and 255 
inclusive for each component of the color. 
rgbval = RGB(Int (256 * Rnd), Int (256 * Rnd), Int(256 * Rnd) ) 
' Set the pixel to the color above. 
retval = SetPixelV(Forml.hDC, x, y, rgbval) 
Next x 
Next y 





See Also 


GetPixel, SetPixel 

Category 

Bitmaps 

Go back to the alphabetical Function listing. 
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Go back to the Reference section index. 
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SetProp Function 


Declare Function SetProp Lib "user32.dll" Alias "SetPropA" (ByVal hWnd As 
Long, ByVal lpString As String, ByVal hData As Long) As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


SetProp sets the value of one of the window properties of a window. If the window property does not already 
exist, this function will also create it. If the window property already exists, this function merely changes its 
value. Any window properties which your program creates must eventually be removed via the RemoveProp 


function. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to set a window property of. 
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lpString 
The name of the window property to set. 
hData 
A handle to the data to set as the window property. This handle can refer to anything you wish. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Set the "LookupFile" property of window Forml to a string. 
' This example also shows how to remove the property. 





Dim hStr As Long, pStr As Long ' handle and pointer to the string 
Dim thevalue As String ' the string referenced by the handle 
Dim retval As Long ' return value 


' Set the value of the string (this could be anything, really). 
thevalue = "C:\Icons\default.ico" 


" Create a memory block... 
hStr = GlobalAlloc (GMEM_ MOVEABLE Or GMEM_ZEROINIT, Len(thevalue) ) 


' ...and copy the string into it. 

















pstr = GlobalLock (hStr) ' get a pointer to the block 
retval = Istrcpy(pStr, text) " copy the string 
retval = GlobalUnlock (hStr) ' release the pointer 








' The handle hStr now refers to a memory block holding the string. Set 
' the "LookupFile" property to this memory block. 

retval = SetProp(Forml.hWnd, "LookupFile", hStr) 

" Note how we cannot yet free the memory block since it is still in use. 











' xxx INSERT OTHER CODE (such as the GetProp example) HERE *** 





' The following code releases the "LookupFile" property and frees 
" the memory block to which it points. 

' (this code assumes the same Dims as above) 

hStr = RemoveProp(Forml.hWnd, "LookupFile") 

' The property is gone; now free the memory block. 

retval = GlobalFree (hStr) 














See Also 


GetProp, RemoveProp 
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Category 


Window Properties 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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SetPolyFillMode Function 


Declare Function SetPolyFillMode Lib "gdi32.dl1" (ByVal hdc As Long, ByVal 
nPolyFillMode As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetPolyFillMode sets the method used by a device to fill polygonal areas and shapes. The two modes differ only 
over complex overlapping polygons, where the edges of the polygon criss-cross each other inside the interior (see 
the example for an example of a complex overlapping polygon). The function returns 0 if an error occured, or 
exactly one of the polygon fill mode flags specifying the filling mode the device had previously been set to. 


hdc 
A device context to the device to set the polygon filling mode of. 
nPolyFillMode 
Exactly one of the following flags specifying the polygon filling mode to use: 
ALTERNATE = 1 
The device alternates between filling and not filling contiguous sections whose boundaries are 
determined by the edge(s) of the polygon crossing through the polygon's interior. 
WINDING = 2 
Any section inside the polygon is filled, regardless of any intra-polygonal boundaries and edges. 


Example: 


' Use the alternating fill mode to fill that five-pointed star that everyone 
' knows so well. Alternating filling tells window Forml not to fill in the 
pentagonal interior 








" of the star. It's hard to describe, so just run the example! 
Dim points (0 to 4) As POINT TYPE ' points of the star 
Dim retval As Long ' return value 


' Load the coordinates of a somewhat distorted five-pointed "pentagram" star 
' design into the array. 


points(0).x = 200: points(0).y = 400 ' Ist point: (200,400) 
points(1).x = 300: points(1l).y = 200 ' 2nd point: (300,200) 
points(2).x = 400: points (2).y = 400 ' 3rd point: (400,400) 
points (3).x = 150: points (3).y = 300 ' 4th point: (150,300) 
points(4).x = 450: points (4).y = 300 ' 5th point: (450,300) 
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' Draw the polygon using alternating fill mode 


retval = SetPolyFillMode (Forml.hDC, ALTERNATE) " set the fill mode 
retval = Polygon(Forml.hDC, points(0), 5) ' draw the polygon 


See Also: GetPolyFillMode 
Category: Regions 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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SetRect Function 


Declare Function SetRect Lib "user32.d1l" (lpRect As RECT, ByVal X1 As Long, 
ByVal Y1 As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetRect sets the position and size of a rectangle. The two coordinates specified are the upper-left and lower-right corners 
of the rectangle. The function returns 0 if an error occured, or 1 if successful. 


IpRect 

The rectangle to set the position and size of. 
XI 

The x coordinate of the upper-left corner of the rectangle. 
Yl 

The y coordinate of the upper-left corner of the rectangle. 
X2 

The x coordinate of the lower-right corner of the rectangle. 
Y2 

The y coordinate of the lower-right corner of the rectangle. 
Example: 
' Set rectangle r to represent the rectangle (20,30)-(100,50). Note 


' that using this function is more efficient and takes less room than setting the 
rectangle's 
' four member values individually. 





Dim r As RECT ' the rectangle to set 
Dim retval As Long ' return value 
retval = SetRect (r, 20, 30, 100, 50) ' r now represents (20,30)-(100,50) 


See Also: SetRectEmpty 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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SetRectEmpty Function 


Declare Function SetRectEmpty Lib "user32.d1l1" (lpRect As RECT) As 
Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetRectEmpty sets a rectangle to an empty state. An empty rectangle is one that has a nonpositive width 
and/or height. In this case, Windows sets the rectangle to (0,0)-(0,0). The function returns 0 if an error 
occured, or | if successful. 


IpRect 
The rectangle to set as empty. 


Example: 

' Set rectangle r to empty. Note this is much easier than manually 
' setting its four member values to 0 individually. 

Dim r AS RECT ' the rectangle to make empty 

Dim retval As Long ' return value 

retval = SetRectEmpty (r) ' r now equals (0,0)-(0,0) 


See Also: IsRectEmpty, SetRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
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SetSysColors Function 
Declare Function SetSysColors Lib "user32.d11" (ByVal cElements As Long, lpaElements 




















As Long, lpaRgbValues As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetSysColors changes the system colors used by Windows. Windows uses these colors when displaying the typical widgets 
such as title bars, scroll bars, the desktop, menus, etc. This function can set multiple different system colors simultaneously, by 
passing all the new RGB color values in an array. SetSysColors also notifies all windows of the change, so the color change 
takes effect immediately. However, the new colors are not saved after Windows shuts down. 


Return Value 


If successful, the function returns a nonzero value. If an error occured, the function returns zero (use GetLastError to get the 
error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


cElements 
The number of elements in the arrays passed as /paElements and IpaRgbValues. 
lpaElements 
An array holding the identifiers of all the system colors to change. Each element can be one of the following flags, 
specifying a system color: 
COLOR_3DDKSHADOW 
The dark shadow color for 3D objects. 
COLOR_3DFACE, COLOR_BTNFACE 
The face color for 3D objects. 
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COLOR_3DHILIGHT, COLOR_3DHIGHLIGHT, COLOR_BTNHILIGHT, COLOR_BTNHIGHLIGHT 
The highlight (opposite of shadow) color for 3D objects. 
COLOR_3DLIGHT 
The light (opposite of shadow) color for 3D objects. 
COLOR_3DSHADOW, COLOR_BTNSHADOW 
The shadow color for 3D objects. 
COLOR_ACTIVEBORDER 
The active window border color. 
COLOR_ACTIVECAPTION 
The active window title bar color. Windows 98, 2000: The color of the left side of the active window title bar 
gradient, if the gradient effect is used. 
COLOR_APPWORKSPACE 
The background color of multiple document interface (MDI) windows. 
COLOR_BACKGROUND, COLOR_DESKTOP 
The desktop color. 
COLOR_BTNTEXT 
The text color for pushbuttons. 
COLOR_CAPTIONTEXT 
The color of window caption text, size boxes, and scroll bar arrow boxes. 
COLOR_GRADIENTACTIVECAPTION 
Windows 98, 2000: The color of the right side of the active window title bar gradient, if the gradient effect is 
used. 
COLOR_GRADIENTINACTIVECAPTION 
Windows 98, 2000: The color of the right side of an inactive window's title bar gradient, if the gradient effect is 
used. 
COLOR_GRAYTEXT 
The color for disabled (grayed-out) text. 
COLOR_HIGHLIGHT 
The color used to highlight selected items. 
COLOR_HIGHLIGHTTEXT 
The color used for the text of highlighted items. 
COLOR_HOTLIGHT 
Windows 98, 2000: The color of a hot-tracked item, which is executed with a single click. 
COLOR_INACTIVEBORDER 
The color of an inactive window's border. 
COLOR_INACTIVECAPTION 
The color of an inactive window's caption. Windows 98, 2000: The color of the right side of an inactive 
window's title bar gradient, if the gradient effect is used. 
COLOR_INACTIVECAPTIONTEXT 
The color of an inactive window's caption text. 
COLOR_INFOBK 
The background color for tooltop controls. 
COLOR_INFOTEXT 
The text color for tooltip controls. 
COLOR_MENU 
The background color of menus. 
COLOR_MENUTEXT 
The color of menu text. 
COLOR_SCROLLBAR 
The color of a scroll bar's gray area. 
COLOR_WINDOW 
The background color of a window. 
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COLOR_WINDOWFRAME 
The color of a window frame. 
COLOR_WINDOWTEXT 
The color of text in a window. 
lpaRgbValues 
An array of the RGB values of the new system colors to assign. These elements correspond directly to the elements in 
lpaElements. For example, the first element of this array is the color to use for the system color identified by the first 
element of [paElements, etc. 


Constant Definitions 











































































































































































































































































































































































































Const COLOR_3DDKSHADOW = 21 

Const COLOR_3DFACE = COLOR_BTNFACE 

Const COLOR_3DHIGHLIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_3DHILIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_3DLIGHT = 22 

Const COLOR_3DSHADOW = COLOR_BTNSHADOW 
Const COLOR_ACTIVEBORDER = 10 

Const COLOR_ACTIVECAPTION = 2 

Const COLOR_APPWORKSPACE = 12 

Const COLOR_BACKGROUND = 1 

Const COLOR_BTNFACE = 15 

Const COLOR_BTNHIGHLIGHT = 20 

Const COLOR_BTNHILIGHT = COLOR_BTNHIGHLIGHT 
Const COLOR_BTNSHADOW = 16 

Const COLOR_BTNTEXT = 18 

Const COLOR_CAPTIONTEXT = 9 

Const COLOR_DESKTOP = COLOR_BACKGROUND 
Const COLOR _GRADIENTACTIVECAPTION = 27 
Const COLOR_GRADIENTINACTIVECAPTION = 28 
Const COLOR_GRAYTEXT = 17 

Const COLOR_HIGHLIGHT = 13 

Const COLOR_HIGHLIGHTTEXT = 14 

Const COLOR_HOTLIGHT = 26 

Const COLOR_INACTIVEBORDER = 11 

Const COLOR_INACTIVECAPTION = 3 

Const COLOR_INACTIVECAPTIONTEXT = 19 
Const COLOR_INFOBK = 24 

Const COLOR_INFOTEXT = 23 

Const COLOR_MENU = 4 

Const COLOR_MENUTEXT = 7 

Const COLOR_SCROLLBAR = 0 

Const COLOR_WINDOW = 5 

Const COLOR_WINDOWFRAME = 6 

Const COLOR_WINDOWTEXT = 8 

Example 


Reverse the gradient colors in windows ' title bars. In other words, the left-side gradient color is swapped with the right-side 
gradient color, for both active and inactive windows. After making the change, a notification is sent to all windows, to insure 
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that the change takes effect immediately. Of course, this example won't work properly on Windows 95 or Windows NT 3.1 
through 4.0, but you can still see how these two functions are used by looking at the source code. 


This example runs when the user clicks command button Command1. So, to use this example, you must first place a command 


button named Command! on a form window. 


' This code is licensed according to the tern 


' Declarations and such needed for the example: 





























ns and conditions listed here. 
















































































' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetSysColor Lib "user32.dll1" (ByVal nIndex As Long) As Long 
Public Declare Function SetSysColors Lib "user32.d1l1" (ByVal cElements As Long, 
lpaElements As Long, 
lpaRgbValues As Long) As Long 
Public Const COLOR_ACTIVECAPTION = 2 
Public Const COLOR _GRADIENTACTIVECAPTION = 27 
Public Const COLOR _GRADIENTINACTIVECAPTION = 28 
Public Const COLOR_INACTIVECAPTION = 3 
' ***x Place the following code inside a form window. *** 
Private Sub Command1_Click () 
Dim activeLeftColor As Long ' color of left-side gradient of active 
window title bar 
Dim activeRightColor As Long ' color of right-side gradient of active 
window title bar 
Dim inactiveLeftColor As Long " color of the left-side gradient of inactive 
window title bar 
Dim inactiveRightColor As Long ' color of the right-side gradient of 
inactive window title bar 
Dim colorNames(0 To 3) As Long ' identifiers of the system colors to change 
Dim colorRGBs(0 To 3) As Long " RGB values of the system colors to change 
Dim retval As Long ' generic return value 
' Get the RGB values of the colors used in title bars. 
activeLeftColor = GetSysColor (COLOR_ACTIVECAPTION) 
activeRightColor = GetSysColor (COLOR_GRADIENTACTIVECAPTION) 
inactiveLeftColor = GetSysColor (COLOR_INACTIVECAPTION) 
inactiveRightColor = GetSysColor (COLOR_GRADIENTINACTIVECAPTION) 




























































































' Load the arrays wi 





















































th the new values 
































o assign. 





Note how we're switching 


sides of the two gradients. 









































" the values used on the left and right 
colorNames (0) = COLOR_ACTIVECAPTION 
colorRGBs(0) = activeRightColor 
colorNames (1) = COLOR_GRADIENTACTIVECAPTION 
colorRGBs(1) = activeLeftColor 
colorNames (2) = COLOR_INACTIVECAPTION 
colorRGBs(2) = inactiveRightColor 
colorNames (3) = COLOR_GRADIENTINACTIVECAPT 


























ON 
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colorRGBs(3) = inactiveLeftColor 





' Change the system color settings as specified above. 
retval = SetSysColors (4, colorNames(0), colorRGBs (0) ) 





End Sub 





See Also 


GetS ysColor 


Category 


System Information 


Back to the Function list. 
Back to the Reference section. 








Last Modified: September 24, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/setsyscolors.html 
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SetSystemCursor Function 


Declare Function SetSystemCursor Lib "user32.d11" (ByVal hcur As Long, 
ByVal id As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetSystemCursor changes one of the cursors that Windows provides. For example, this function can 
change the cursor used to represent the default arrow cursor. Be careful using this function, since this 
redefines the default cursors instead of simply setting the current look of the cursor. The function destroys 
the cursor handle passed to it once it sets the new default cursor. The function returns 1 if successful, or O if 
an error occured. 


hcur 
A handle to the cursor to use as the new default cursor for a given type of cursor. The function 
destroys this handle once the new cursor is set. 


Exactly one of the following flags specifying which of the Windows default cursors to redefine: 
OCR_APPSTARTING = 32650 
The application starting (arrow and hourglass) cursor. 
OCR_CROSS = 32515 
The cross-shaped cursor. 
OCR_IBEAM = 32513 
The text selection (I-beam) cursor. 
OCR_ICON = 32641 
Win NT only: The empty icon cursor. 
OCR_NO = 32648 
The "no"-symbol (circle with slash through it) cursor. 
OCR_NORMAL = 32512 
The normal arrow cursor. 
OCR_SIZE = 32640 
Win NT only: The four-arrow resize/move cursor. 
OCR_SIZEALL = 32646 
The four-arrow resize/move cursor. 
OCR_SIZENESW = 32643 
The double-arrow resize/move cursor pointing to the upper-right and lower-left. 
OCR_SIZENS = 32645 
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The double-arrow resize/move cursor pointing up and down. 
OCR_SIZENWSE = 32642 

The double-arrow resize/move cursor pointing to the upper-left and lower-right. 
OCR_SIZEWE = 32644 

The double-arrow resize/move cursor pointing left and right. 
OCR_UP = 32516 

The up arrow cursor. 
OCR_WAIT = 32514 

The waiting (hourglass) cursor. 


Example: 


' Set Windows's default "hourglass" cursor to the cursor in 

' C:\MyProg\NewWait.ani. 

Dim hcursor As Long ' receives handle to the cursor from the file 
Dim retval As Long ' return value 


' Load the desired cursor from the file: 
heursor = LoadCursorFromFile ("C:\MyProg\NewWait.ani") 





retval = SetSystemCursor (hcursor, OCR_WAIT) ' redefine hourglass cursor 
' Now Windows will use NewWait.ani as the hourglass cursor. 


See Also: SetCursor 
Category: Cursor 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/setsystemcursor.html 
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SetSystemTime Function 


Declare Function SetSystemTime Lib "kernel32.d1l1" (lpSystemTime As 
SYSTEMTIME) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetSystemTime sets the date and time of the system's clock. The time given to the function must be in UTC 
time (Coordinated Universal Time, a.k.a. Greenwich Mean Time (GMT)), not in the system's local time zone. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpSystemTime 
The new time and date to use to set the system clock. The wDayOfWeek member of the structure is 
ignored. 
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Example 


' This code is licensed according to the terms and conditions listed here. 


' Set the system clock to the following time: 
* October 3, 1999 16:46:00 UTC 
Dim systime As SYSTEMTIME ' new time and date 


Dim retval As Long ' return value 








' Put the date information into the structure. 





systime.wYear = 1999 
systime.wMonth = 10 
systime.wDay = 3 
systime.wHour = 16 
systime.wMinute = 46 
systime.wSecond = 0 
systime.wMillisecond = 0 





" Set the system clock to that time and date. 
retval = SetSystemTime (systime) 


See Also 
GetSystemTime 
Category 
Time 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: October 3, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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SetTextAlign Function 


Declare Function SetTextAlign Lib "gdi32.dll1" (ByVal hdc As Long, ByVal wFlags 
As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SetTextAlign specifies how a device displays text relative to a given reference point. The reference point is the point 
used to identify where a line of text should be written. The function returns 1 if successful, or 0 if an error occured. 


hdc 
The device context of the device to set the reference point alignment of. 
wFlags 

Up to three of the following flags specifying where the text will be written in relation to a given reference point. 
Only one flag may be specified for horizontal alignment, vertical alignment, and current point updating. 
TA_BASELINE = 24 

The reference point will be on the baseline of the text. 
TA_BOTTOM = 8 

The reference point will be on the bottom edge of the bounding rectangle of the text. 
TA_CENTER = 6 

The reference point will be horizontally centered along the bounding rectangle of the text. 
TA_LEFT = 0 

The reference point will be on the left edge of the bounding rectangle of the text. 
TA_NOUPDATECP = 0 

Do not set the current point to the reference point. 
TA_RIGHT = 2 

The reference point will be on the right edge of the bounding rectangle of the text. 
TA_RTLREADING = 256 

Win 95/98 only:Display the text right-to-left (if the font is designed for right-to-left reading). 
TA_TOP =0 

The reference point will be on the top edge of the bounding rectangle of the text. 
TA_UPDATECP = 1 

Set the current point to the reference point. 


Example: 
' Display the text "Hello, world!" on window Forml at (100,50). 


" Center the text horizontally at that point and have it appear below the point. 
Dim retval As Long ' return value 





' Set the reference point to be centered horizontally and on the top edge of the 


text: 
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retval = SetTextAlign(Forml.hDC, TA_CENTER Or TA_TOP Or TA_NOUPDATECP) 
' Display the text: 
retval = TextOut (Forml.hDC, 100, 50, "Hello, world!", 13) 


See Also: GetTextAlign, TextOut 
Category: Fonts & Text 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
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This page is at http://www.vbapi.com/ref/s/settextalign.html 
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SetThreadLocale Function 


Declare Function SetThreadLocale Lib "kernel32.d11" (ByVal Locale As Long) As 
Long 


Platforms 


Windows 95: Not Supported. 

Windows 98: Not Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetThreadLocale chooses which locale to assign to the thread calling the function (i.e., the thread from your 
program). This locale should then be used whenever the program displays certain data to the user. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a 
non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


Locale 
The identifier of the locale to assign to the calling thread. This can also be one of the following flags: 
LOCALE_SYSTEM_DEFAULT 
The system's default locale. 
LOCALE_USER_DEFAULT 
The user's default locale. 


http://216.26.168.92/vbapi/ref/s/setthreadlocale.html (1 of 3) [9/1/2002 5:45:30 PM] 


Windows API Guide: SetThreadLocale Function 


Constant Definitions 





Const LOCALE_SYSTEM_DEFAULT = &H400 
Const LOCALE_USER_DEFAULT = &H800 








Example 


' This code is licensed according to the terms and conditions listed here. 


' Assign the system's current locale to this thread. Note that 

" this could be significantly different than the locale previously 
" assigned to the thread! Then use the newly selected locale 

' to display the current date. 

Dim retval As Long ' return value 

Dim today As SYSTEMTIME ' today's date and time 


vas 


Dim datestr As String ' receives the formatted date string 
Dim strlen As Long ' length of the buffer for the formatted date string 








' First of all, set the locale to the system's default. 
retval = SetThreadLocale (LOCALE SYSTEM DEFAULT) 





' Get today's date and time in the local time zone. 
GetLocalTime today 





' Make sufficient room in the buffer to receive the date string. 

datestr = Space (255) 

' Format today's date as a Long Date. 

strlen = GetDateFormat (0, DATE_LONGDATE, today, CLng(0), datestr, Len(datestr) ) 
" Remove the empty space from the formatted date string. 

datestr = Left(datestr, strlen) 

' Display today's date as a Long Date. 

Debug.Print "Today is "; datestr 





See Also 


GetThreadLocale 


Category 


National Language Support 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Last Modified: January 4, 2000 
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SetTimer Function 

















Declare Function SetTimer Lib "user32.dl11" (ByVal hWnd As Long, ByVal nIDEvent As 
Long, ByVal uElapse As Long, ByVal lpTimerFunc As Long) As Long 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetTimer creates a timer that triggers an event after so many milliseconds have elapsed. The timer continues triggering events 
between intervals until it is removed using KillTimer. The timer can be configured to either send a WM_TIMER message to 


the owning window or call a callback function whenever the time-out period elapsed. 


Return Value 


If successful, the function returns a unique integer identifying the created timer. If an error occured, the function returns 0 (call 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window that will own the timer. To make the timer unassociated with any window, set this to 0. 
nIDEvent 
A nonzero value that will be used to identify the timer. If hWnd is 0, this parameter is ignored. 
uElapse 
The time-out period, in milliseconds, to elapse between timer notifications. 
[pTimerFunc 
A pointer to the TimerProc callback function to call whenever the time-out period elapses. If this is 0, a WM_TIMER 
message is instead sent to the window specified by hWnd when the time-out period elapses. 
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Example 


Display the current time in text box control Textl. The time is updated twice every second, and the time is formatted according 
to the current locale's settings. To use this example, place a text edit box named Text! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 


" (Copy 














them to the (declarations) 
Public Type SYSTEMTIME 














wYear As Integer 
wMonth As Integer 





wDay As Integer 





wDayOfWeek As Integer 


wHour As Integer 


wMinute As Integer 
wsecond As Integer 
wMilliseconds As Integer 





End Type 
Public Declare Function SetTimer Lib 





As Long, ByVal u 








ublic Declare Function 
t As Long) As Long 








P 
niIDEvent 
P 

( 





As Any, 


ublic Declare Funct 


ByVal _ 


Locale As Long, 


ByVal lpTimeStr 





KillTimer Lib 




















section of a module.) 














"user32.dl1l1" (ByVal hWnd As Long, ByVal nIDEvent 











Elapse As Long, ByVal lpTimerFunc As Long) As Long 








"user32.d1ll1" (ByVal hWnd As Long, ByVal 





tion GetTimeFormat Lib "kernel32.d11" Alias "GetTimeFormatA" 














ByVal dwFlags As Long, lpTime As SYSTEMTIME, ByVal lpFormat 








As String, ByVal cchTime As Long) As Long 


' *** Place the following code inside a module. *** 


' The following 
' the current tin 


E 


unction will 








preferences. 





Public Sub TimerProc (ByVal 




















' Retrieve the current time, 








ByVal dwTime As Long) 

Dim systime As SYSTEMTIME l 
Dim timestr As String * 260 '! 
Dim slength As Long $ 

















GetLocalTime systime 





execute twice every second. It retrieves 
ne and displays it according to the current locale's formatting 




















hwnd As Long, ByVal uMsg As Long, ByVal idEvent As Long, 


the current time 








receives the formatted string 
length of formatted string returned 

















according to the computer's time zone. 


' Format a string to represent the time. 
slength = GetTimeFormat (0, 0, 











' Display the st 


tring in Textl, 








Forml.Textl1.Tex 


End Function 








systime, CLng(0), timestr, Len(timestr) ) 





found on window Forml. 


t = Left (timestr, slength) 





' *** Place the following code inside Forml. *** 
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' Create the timer when the form opens and destroy it when the form closes. 

' The timer is given an ID of 1, so the return values don't need to be saved. 
Private Sub Form_Load() 

Dim retval As Long ' return value 


























retval = SetTimer(Forml.hWnd, 1, 500, AddressOf TimerProc) 
End Sub 





Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 





retval = KillTimer(Forml.hWnd, 1) 
End Sub 





See Also 


KillTimer 


Category 


Timers 


Back to the Function list. 
Back to the Reference section. 








Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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SetVolumeLabel Function 


Declare Function SetVolumeLabel Lib "kernel32.d11" Alias "SetVolumeLabelA" (ByVal 
lpRootPathName As String, ByVal lpVolumeName As String) As Long 




















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetVolumeLabel sets the label of a file system volume. The new volume label must comply with length constaints and 
cannot contain any invalid characters. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpRootPathName 
The path of the root directory of the drive to set the file system volume label of. This path must include the trailing 
backslash. For example, the C: drive would be "C:\". 

lp VolumeName 
The new name to assign to the volume. 


Example 


' This code is licensed according to the terms and conditions listed here. 


http://216.26.168.92/vbapi/ref/s/setvolumelabel.html (1 of 2) [9/1/2002 5:45:52 PM] 


Windows API Guide: SetVolumeLabel Function 


' Declarations and such needed for the example: 
' (Copy these to the (declarations) section of a module.) 





Public Declare Function SetVolumeLabel Lib "kernel32.d11" Alias "SetVolumeLabelA" _ 














(ByVal lpRootPathName As String, ByVal lpVolumeName As String) As Long 








' Set the file system volume label of the C: drive to "MYDRIVE". 
Dim retval As Long ' return value 











' Set the new volume label. 
retval = SetVolumeLabel ("C:\", "MYDRIVE") 








See Also 


GetVolumeInformation 


Category 


File System 


Back to the Function list. 
Back to the Reference section. 
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SetWindowLong Function 





Declare Function SetWindowLong Lib "user32.dl1" Alias "SetWindowLongA" (ByVal hWnd 
As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetWindowLong sets a 32-bit value constituting the information about a window. This function can also set a 32-bit value 
within the block of extra memory given to the window, if such a block exists. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the 
previous setting of whatever 32-bit value was replaced. 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to set a 32-bit value in. 
nIndex 
To set a 32-bit value within the window's extra memory block, this is the zero-based offset of the byte to begin writing 
to. Valid values range from 0 to the size of the extra memory block in bytes minus four. To set a 32-bit value of one of 
the properties of the window, this is one of the following flags specifying which piece of information to set: 
GWL_EXSTYLE 
Set the extended window styles of the window. dwNewLong is the new setting. 
GWL_HINSTANCE 
Set which application instance is considered to own the window. dwNewLong is the new setting. 
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GWL_HWNDPARENT 
Retrieve a handle to the parent window, if any. dwNewLong is a handle to the instance to set as the owner. 
GWL_ID 
Set the identifier of the window. dwNewLong is the new identifier. 
GWL_USERDATA 
Set the application-defined 32-bit value associated with the window. dwNewLong is the new value. 
GWL_STYLE 
Retrieve the window styles of the window. 
GWL_WNDPROC 
Set the WindowProc hook function to use as the window's procedure. dwNewLong is a pointer to the hook 
function to set as the window procedure. 
If the window happens to be a dialog box, this could also be one of the following flags: 
DWL_DLGPROC 
Set the WindowProc hook function to use as the dialog box procedure. dwNewLong is a pointer to the hook 





function to set as the window procedure. 
DWL_MSGRESULT 
Set the return value of the last message processed by the dialog box. dwNewLong is the new value. 
DWL_USER 
Set the application-defined 32-bit value associated with the dialog box. dwNewLong is the new value. 
dwNewLong 
The 32-bit value to set as specified by nIndex. 


Constant Definitions 


Const GWL_EXSTYLE = -20 
Const GWL_HINSTANCE = -6 
Const GWL_HWNDPARENT = -8 
Const GWL_ID = -12 

Const GWL_STYLE = -16 
Const GWL_USERDATA = -21 
Const GWL_WNDPROC = -4 
Const DWL_DLGPROC = 4 
Const DWL_MSGRESULT = 0 
Const DWL_USER = 8 























Example 


Have a window play the SystemAsterisk sound whenever it gains or loses the focus. This is done by playing the sound 
whenever the window receives the WM_ACTIVATE message. To use this example, copy the following code into the proper 
locations. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 
Public Declare Function SetWindowLong Lib "user32.dl1" Alias "SetWindowLongA" (ByVal 
hWnd As Long, _ 

ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 


Public Const GWL_WNDPROC = -4 
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Public Declare Function CallWindowProc Lib "user32.d11" 


Alias "CallWindowProcA" 








(ByVal lpPrevWndFunc _ 

As Long, ByVal hWnd As Long, ByVal Msg As Long, 
lParam As Long) As Long 
Public Declare Function PlaySound Lib "winmm.dll" Alias 
As Any, ByVal _ 

hModule As Long, ByVal dwFlags As Long) As Long 
Public Const WM_ACTIVATE = &H6 





xxx Place this code in a module. *** 


ByVal wParam As Long, ByVal 


"PlaySoundA" (ByVal lpszName 


' The following variable is accessible to all code in this example. 


Public pol 











' Define the new window procedure. 


l\dProc As Long ' pointer to the previous window function 


Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 


Long, 





ByVal lParam As Long) As Long 
Dim retval As Long ' return value 





' If the message is WM_ACTIVATE (we don't care about the parameters), 





play the SystemAsterisk sound. 
If uMsg = WM_ACTIVATE Then 
retval = PlaySound("SystemAsterisk", 0, 





End If 


finish processing the message. 





SND_ALIAS Or SND_ASYNC) 


No matter what happened, use the old window procedure to 


retval = CallWindowProc(pOldProc, hWnd, uMsg, wParam, lParam) 
' Have this function return whatever the function above returned. 








WindowProc = retval 
End Function 


*** Place the following code in the form window. *** 


Private Sub Form_Load () 
Dim retval As Long ' return value 














Set the new window procedure for Forml, saving a pointer to the old one. 


pOldProc = SetWindowLong (Me.hWnd, GWL_WNDPROC, AddressOf WindowProc) 





End Sub 


Private Sub Form_Unload (Cancel As Integer) 
Dim retval As Long ' return value 





Restore the window's procedure before closing. 








retval = SetWindowLong(Me.hWnd, GWL_WNDPROC, pOldProc) 





End Sub 


See Also 


GetWindowLong, SetClassLong 
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Window Classes 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setwindowlong.html 
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SetWindowPos Function 











Declare Function SetWindowPos Lib "user32.dll1" (ByVal hwnd As Long, ByVal 
hWndiInsertAfter As Long, ByVal x As Long, ByVal y As Long, ByVal cx As Long, ByVal cy 
As Long, ByVal wFlags As Long) As Long 
































Platforms: Win 32s, Win 95/98, Win NT 


SetWindowPos moves a window to a new location on the screen. Its physical coordinates, dimensions, and Z-order position 
(the Z-order determines which windows are on top of others) can be set. The function returns 0 if an error occured or | if 
successful. 


hwnd 
The handle of the window to move. 
hWndInsertAfter 
Either the handle of the window to position this window behind, or exactly one of the following flags stating where in 
the Z-order to put the window: 
HWND_BOTTOM = 1 
Put the window at the bottom of the Z-order. 
HWND_NOTOPMOST = -2 
Put the window below all topmost windows and above all non-topmost windows. 
HWND_TOP = 0 
Put the window at the top of the Z-order. 
HWND_TOPMOST = -1 
Make the window topmost (above all other windows) permanently. 


x 

The x coordinate of where to put the upper-left corner of the window. 
y 

The y coordinate of where to put the upper-left corner of the window. 
cx 

The x coordinate of where to put the lower-right corner of the window. 
cy 


The y coordinate of where to put the lower-right corner of the window. 
wFlags 

Zero or more of the following flags stating how to move the window: 
SWP_DRAWFRAME = &H20 

Same as SWP_FRAMECHANGED. 
SWP_FRAMECHANGED = &H20 

Fully redraw the window in its new position. 
SWP_HIDEWINDOW = &H80 

Hide the window from the screen. 
SWP_NOACTIVATE = &H10 

Do not make the window active after moving it unless it was already the active window. 
SWP_NOCOPYBITS = &H100 

Do not redraw anything drawn on the window after it is moved. 
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SWP_NOMOVE = &H2 
Do not move the window. 
SWP_NOSIZE = &H1 
Do not resize the window. 
SWP_NOREDRAW = &H8 
Do not remove the image of the window in its former position, effectively leaving a ghost image on the screen. 
SWP_NOZORDER = &H4 
Do not change the window's position in the Z-order. 
SWP_SHOWWINDOW = &H40 
Show the window if it is hidden. 





Example: 


' Move window Forml to the upper-left corner of the screen and make 

' at appear above all other windows permanently. Note how the function is told not 
' to resize the window, so we don't have to worry about the lower-right coordinate. 
Dim flags As Long ' the flags specifying how to move the window 

Dim retval As Long ' return value 























" Do not resize the window, redraw the window in its new location 
flags = SWP_NOSIZE Or SWP_DRAWFRAME 
retval = SetWindowPos (Forml.hWnd, HWND_TOPMOST, 0, 0, 1, 1, flags) ' move the window 


























See Also: Bring WindowToTop, GetWindowRect, MoveWindow 
Category: Windows 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/setwindowpos.html 
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SetWindowRgn Function 





Declare Function SetWindowRgn Lib "user32.d11" (ByVal hWnd As Long, ByVal hRgn As 
Long, ByVal bRedraw As Boolean) As Long 

















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.51 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SetWindowRgn changes the visible region of a window. Using this function, you can make a window appear non-rectangular. 
Any portion of the window lying outside of the region is not drawn, and so is invisible. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (Windows NT/2000: use 
GetLastError to get the error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


hWnd 
A handle to the window to set the region of. 

hRgn 
A handle to a region that defines what to make the visible area of the window. If this is zero, the entire window is 
displayed (effectively removing any special region set previously). 

bRedraw 
Specifies whether to immediately redraw the window using its new region or not. If this is True, the window is redrawn. 
If this is False, it is not. 


Example 
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Use an elliptic region to make window Form1 appear elliptical. Notice how, as this example is written, a portion of the title bar 
is still visible after applying the region. This allows us to move the window without adding any special code providing a 
different way for the user to move the window. Normally, in a real program, you would not want the title bar to be displayed, 
but after all, this is just an example. At least it shows you that the region only changes what part of the window you can see -- 
it doesn't change anything else about the window. 


To run this example, make two windows Form1 and Form2. The latter will be used to illustrate GetWindowRgn. Place the 
following three buttons on Form1: a button labeled "Apply Region" and named cmdApplyRegion, a button labeled "Remove 
Region" and named cmdRemoveRegion, and a button labeled "Show Region" and named cmdShowRegion. Place these 
buttons near the center of Form! to make sure parts of them won't be hidden when the region is applied. 





' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function GetWindowRgn Lib "user32.dl1l1" (ByVa 





hWnd As Long, ByVal hRgn 











As Long) As Long 
Public Declare Function SetWindowRgn Lib "user32.dll1" (ByVa 
As Long, 





























hWnd As Long, ByVal hRgn 








ByVal bRedraw As Boolean) As Long 
Public Declare Function CreateFllipticRgn Lib "gdi32.dl1l1l' 

















~ 


ByVal nLeftRect As Long, 











ByVal nTopRect _ 
As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long) As Long 
Public Declare Function DeleteObject Lib "gdi32.dl1ll1" (ByVal hObject As Long) As Long 


Public Declare Function InvertRgn Lib "gdi32.dl1" (ByVal hdc As Long, ByVal hrgn As 


















































Long) As Long 
' *** Place the following code inside Forml. *** 


' Stores a handle to the special window region, if it exists. 
Private hRgnWindow As Long 





Private Sub Form_Load() 
' Open Form2 when this loads. Form2 is used to display a sort of 
' "shadow" of the region used by Forml, although it really isn't a shadow 

















effect. 
Form2.Show 
' Initially disable the "Remove Region" button, sice one hasn't 
' yet been applied. 
cmdRemoveRegion.Enabled = False 
End Sub 





Private Sub cmdApplyRegion_Click () 
' Create an elliptic region slightly smaller than the current size of 
' Forml, and make that the window region. This makes the previously 
' rectangular Forml appear to be an ellipse. 








Dim retval As Long ' return value 





' First, make the elliptical region, slightly smaller than Forml. 
hRgnWindow = CreateEllipticRgn(5, 5, (Forml.Width / Screen.TwipsPerPixelX) - 
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Sy 


' Apply this region 


re 


(Forml.Height / Sc 


tval = 


To make 
this bu 





SetWindowRgn (Form 


sure that multip 





reen.TwipsPerPixelY) - 5) 





to Forml and show the change immediately. 


1.hWnd, hRgnWindow, True) 


le regions aren't created, disable 





tton and enable the "Remove Region" button. 








cmdApplyRegion.Enabled = F 


cm 
End Sub 





Private Su 





' 


re 


re 


' 


cm 





dRemove 


b cm 








Region.Enabled = 


alse 
True 


dRemoveRegion_Click () 


Remove the window region from Forml, returning it to its 
normal rectangular shape. 








set an 
tval = 


Dim retval As Long ' retu 


ull window region 
SetWindowRgn (Form 





rn value 


, which removes the current one entirely. 
1.hWnd, 0, True) 








Delet 





the region object 








tval = 


DeleteObject (hRgn 





because it is no longer needed. 
Window) 


Since the region no longer exists, enable "Apply Region" and 


disable 





this button. 


= 





dApplyRegion.Enabled = T 








cmdRemoveRegion.Enabled = 


End Sub 





Private Sub cmdShowRegion_Click () 
Show the region currently applied to Forml by inverting that region on 


' 


because 





Di 


' 

y 
NR 

' 

' 


re 


' 


las 


re 
End Sub 





Form2. 


Note that if no 





rue 
False 


region is applied, nothing appears to happen 





the actual window region is empty. 


Dim hRgnCopy As Long ' re 


m retval As Long ' re 





Create 
when Ge 


gnCopy 


Copy Forml's region to h 
does not change, but the 


tval = 





Invert 
tval = 
Delete 
tval = 








a region. It doe 
tWindowRgn is cal 


gion that receives copy of Forml's region 
turn value 





sn't matter what, since it will be overwritten 
led. We just need to have some region. 





= CreateEllipticRgn(0, 0, 0, 0) 











GetWindowRgn (Form 





the colors on For 
InvertRgn (Form2.h 
the copied region 











See Also 


GetWindowRgn 





DeleteObject (hRgn 





RgnCopy. The actual value of the handle 
information it "points" to does. 

1.hWnd, hRgnCopy) 

m2 that lie within this region. 

DC, hRgnCopy) 

, since we no longer need it. 

Copy) 
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Category 


Painting & Drawing 





Back to the Function list. 
Back to the Reference section. 





Last Modified: September 24, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/setwindowrgn.html 
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SetWindowText Function 


Declare Function SetWindowText Lib "user32.d11" Alias "SetWindowTextA" 
(ByVal hWnd As Long, ByVal lpString As String) As Long 


Platforms 


e Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SetWindowText changes the text of a given window. Although this function can set the text of regular 
windows owned by other programs, it cannot change the text of a control owned by a different program. To 
set the text of those controls, use the WM_SETTEXT message instead. 





Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Parameters 


hWnd 
A handle to the window to set the text of. 


IpString 
The string to set as the window's text. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Set the title bar of window Forml to "Generic Application 1.0". 
Dim retval As Long ' return value 





retval = SetWindowText (Forml.hWnd, "Generic Application 1.0") 


See Also 


GetWindowText, WM _SETTEXT 


Category 


Windows 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





Last Modified: February 12, 2000. 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/setwindowtext.html 
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SHAddToRecentDocs Function 


Declare Sub SHAddToRecentDocs Lib "shell32.d11" (ByVal uFlags As Long, 
ByVal pv As Any) 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SHAddToRecentDocs adds a shortcut to a file to the shell's Documents menu under the Start menu. To 
accomplish this, the function creates a shortcut to the file under the Recent directory (the folder identified by 
the CSIDL CSIDL_RECENT). Instead of adding a file to the Documents menu, this function can also clear 
the entire contents of the Documents menu. 


Return Value 


SHAddToRecentDocs does not return a value. 


Visual Basic-Specific Issues 


When passing 0 for the pv parameter, you must use the expression CLng(Q) to pass it correctly. 


Parameters 


uFlags 
Either one of the following flags specifying the nature of the pv parameter, or O to clear the contents of 
the Documents menu. 
SHARD_PIDL 
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pv is a pointer to an ITEMIDLIST structure (a PIDL) identifying the file to add to the 
Documents menu. 
SHARD_PATH 
pv is the filename of the file to add to the Documents menu. 
pvidentifies the file to add to the Documents menu. It is either a PIDL or a string, depending on the value 
passed as uFlags. If uFlags is 0, this must also be 0. 


Constant Definitions 


Const SHARD_PIDL = 1 
Const SHARD_PATH 





Il 
N 


Example 


This code is licensed according to the terms and conditions listed here. 


' First, clear the Documents menu. Then add a link to the file 


C:\MyDocs\report.txt to the Documents menu. Of course, you 
should always ask the user before you clear the Documents menu! 

















' Clear the Documents menu entirely. 
SHAddToRecentDocs 0, CLng (0) 





' Then add the file C:\MyDocs\report.txt to the menu. 
SHAddToRecentDocs SHARD PATH, "C:\MyDocs\report.txt" 





Category 
Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: December 28, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/shaddtorecentdocs.html 
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SHBrowseForFolder Function 


Declare Function SHBrowseForFolder Lib "shell132.d11" Alias "SHBrowseForFolderA" 
(lpbi As BROWSEINFO) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SHBrowseForFolder opens the Browse for Folder dialog box, asking the user to select a folder on the system. The folder 
selected can be either a physical path on a disk or a virtual folder. The PIDL obtained by the function, if any, must be freed 


by using the CoTaskMemFree function. 





Return Value 


If an error occured or the user pressed Cancel, the function returns 0. If the user successfully selected a folder, the function 
returns a pointer to an ITEMIDLIST structure (a PIDL) identifying the selection. 





Visual Basic-Specific Issues 
None. 


Parameters 


Ipbi 
Holds all the settings necessary to initialize the Browse for Folder dialog box. This structure also receives some 
information from the function if successful. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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the actual name of the folder (if 
folders under My Computer can be se 
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E 
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This function compensates for the 


folder). 
lected, have the directory 


Although 


odule. *** 


act that the AddressOf operator 











can only be used in a function call 

passed to it. 

Public Function DummyFunc (ByVal paran 
DummyFunc param 

End Function 





n 


This function is the callback funct 


It returns the parameter 


As Long) As Long 


ion for the dialog box. It sets 











the selected folder to C:\StartHer 
































when the box is initialized. 














Public Function BrowseCallbackProc(ByVal hwnd As Long, ByVal uMsg As Long, 
lParam As Long, ByVal lpData As Long) As Long 
Dim pathstring As String ' name of path to set by default 
Dim retval As Long ' return value 
' Tf the BFFM_INITIALIZED message is received, set the 
' default selection to C:\StartHere. 
Select Case uMsg 
Case BFFM_INITIALIZED 
pathstring = "C:\StartHere" ' the path to make the default selection 
' Send a message to the dialog box telling it to select this path. 
' Note the use of ByVal and the CLng function here. 
retval = SendMessage (hwnd, BFFM_SETSELECTION, ByVal CLng(1), ByVal path 








End Select 
BrowseCallbackProc 
End Function 


O the funct 


T £ 


xxx Place the following code where 
*** Browse for Folder dialog box. 
Dim bi As BROWSEINFO ' structure pas 
Dim pidl As Long ' PIDL to the user' 
Dim physpath As String ' string used 
Dim retval As Long ' return value 





’ * 























Initialize the structure to be pass 














ion should always return 


you want to open the *** 


K* 
sed to the function 
s selection 


to temporarily hold the physical path 


ed to the function. 



































bi.hwndOwner = Forml.hWnd ' window Forml is the owner of the dialog box 

' Specify the My Computer virtual folder as the root 

retval = SHGetSpecialFolderLocation(Forml.hWnd, CSIDL_DRIVES, bi.pidlRoot) 
' Make room in the buffer to get the [virtual] folder's display name 
bi.pszDisplayName = Space (260) 

bi.lpszTitle = "Please choose a folder." ' Message displayed to the user 
bi.ulFlags = 0 ' no flags are needed her 

' Identify the callback function to use for the dialog box. Note 





ded becaus 





how our DummyFunc is n 
inside a function call. 
bi.lpfn DummyFunc (AddressOf BrowseC 





AddressOf only works 





allbackProc) 
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0 ' the callback function here doesn't need this 
O ' this will be set by the function 


bi.lParam 
bi.ilImage 





Open the Browse for Folder dialog box. 

pidl = SHBrowseForFolder (bi) 

' If the user selected something, display its display name 
' and its physical location on the system. 


If pidl <> 0 Then 




















Remove th mpty space from the display name variable. 
bi.pszDisplayName = Left (bi.pszDisplayName, InStr(bi.pszDisplayName, 
1) 
Debug.Print "The user selected: "; bi.pszDisplayName 














physpath = Space (260) ' make room in the buffer 
retval = SHGetPathFromIDList(pidl, physpath) 



































If retval = 0 Then 
Debug.Print "Physical Location: (virtual folder)" 
Else 
' Remove th mpty space and display the result. 
physpath = Left (physpath, InStr(physpath, vbNullChar) - 1) 
Debug.Print "Physical Location: "; physpath 
End If 


Free the pidl returned by the function. 
CoTaskMemFree pidl 


End If 





Whether successful or not, free the PIDL which was used to 
identify the My Computer virtual folder. 
CoTaskMemF ree bi.pidlRoot 











Category 
Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Shell_ Notifylcon Function 


Declare Function Shell_NotifyIcon Lib "shel132.d11" Alias "Shell_NotifyIconA" (ByVal 
dwMessage As Long, pnid As NOTIFYICONDATA) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Shell_NotifyIcon manipulates an icon located in the taskbar's status area, commonly referred to as the "system tray." This 
function adds a new icon, removes an existing icon, or changes an existing icon owned by the calling program. Programs 
typically use tray icons when they run in the background without a window; the icon gives the user a way to access the 
running program. 


All of a tray icon's messages are sent to its owner window for processing. See the page for the NOTIFYICONDATA 
structure for more details on how this is done. The standard behavior of Shell_NotifyIcon used the following messages: 
WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_RBUTTONUP, etc. 


























Return Value 


The function returns 0 if an error occured, or a non-zero value if successful. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwMessage 
One of the following flags specifying the action to take: 
NIM_ADD 
Add the icon described by pnid to the system tray. 
NIM_DELETE 
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Remove the icon described by pnid from the system tray. 

NIM_MODIFY 
Modify the icon described by pnid. 

NIM_SETFOCUS 
Windows 2000: Return the focus to the system tray. This should be done after completing the user interface 
operations associated with the icon. 

NIM_SETVERSION 
Windows 2000: Use the uVersion member of the structure passed as pnid to determine which taskbar behavior 
to use. The two options are the Windows 2000-specific behavior and the behavior found on other Windows 
platforms. Note that this guide does not explain how to use the behavior introduced by Windows 2000. 

pnid 
Provides identifying information and settings for the tray icon, as needed by the value passed as dwMessage. 


Constant Definitions 


Const NIM_ADD = &HO 
Const NIM DELETE = &H2 
Const NIM MODIFY = &H1 
N 
N 














Const NIM_SETFOCUS = &H4 
Const NIM_SETVERSION = &H8 











Example 


Note: To use this example, you must first use the Menu Editor utility to create a small menu on Form1. Create a menu called 
mnuTrayIconPopup with its Visible check box cleared. Then, create two menu items under it: mnuAbout and mnuExit. You 
can give those items whatever captions you which; those are what will be displayed in the menu. If you do this properly, you 
will not see a menu bar in Form] but the example code will function properly. 


' This code is licensed according to the terms and conditions listed here. 


' Place an icon in the system tray when window Forml opens. When right- 
clicked, a small pop-up menu appears. The icon is deleted when Forml closes. 
' Notice how the window procedure for Forml is extended in order to process the 


' messages for the icon. Also, note the application-defined message used for tray 
icons. 

















' *** Place the following code in a module. *** 
' Public variable definitions. 




















Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public Const PK_TRAYICON = &H401 ' program-defined message for tray icon action 
' This function acts as the new window procedure for Forml. It handles the program- 


' defined PK_TRAYICON message, used whenever a user event occurs with the 
" tray icon. 
Public Function WindowProc(ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 














Long, ByVal lParam As Long) As Long 
Select Case uMsg 
Case PK_TRAYICON 
' If the user released the right mouse button over the icon, display the 
' mnuTrayIconPopup menu at the mouse cursor's position. Make 
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' mnuAbout the default selection in the menu. 
If lParam = WM RBUTTONUP Then 
Forml.PopupMenu mnuTraylIconPopup, 
End If 
WindowProc = 1 ' this return value doesn't really matter 
Case Else 
' Pass the message to the procedure Visual Basic provided. 
WindowProc = CallWindowProc(pOldProc, hWnd, Msg, wParam, lParam) 
End Select 
End Function 











r , , mnuAbout 














' *** Place the following code in Formi. *** 

' This function creates the tray icon and hooks up the window procedure 
' when Forml first opens. 

Private Sub Forml_Open () 

Dim nid As NOTIFYICONDATA ' icon information 


Dim retval As Long ' return value 























Put the icon settings into the structure. 


























With nid 
.cbSize = Len(nid) ' size of structure 
-hWnd = Forml.hWnd ' owner of the icon and processor of its messages 
-uID = 1 ' unique identifier for the window's tray icons 
.uFlags = NIF_ICON Or NIF_MESSAGE Or NIF_TIP ' provide icon, message, and tool 
tip text 
.uCallbackMessage = PK_TRAYICON ' message to use for icon events 
-hicon = Forml.Icon ' handle to the icon to actually display in the tray 
.szTip = "Sample Tray Icon" & vbNullChar ' tool tip text for icon 
End With 


Add the icon to the system tray. 

retval = Shell_NotifyIcon(NIM_ADD, nid) 

' Set the new window procedure for window Forml. 

pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 
End Sub 

















This function removes the tray icon and returns the old window procedure to use. 
Private Sub Forml_Unload(Cancel As Integer) 
Dim nid As NOTIFYICONDATA ' icon information 


Dim retval As Long ' return value 

















Load the structure with just the identifying information. 











With nid 
.cbSize = Len(nid) ' size of structure 
-hWnd = Forml.hWnd ' handle of owning window 
-uId = 1 ' unique identifier 

End With 


Remove the icon from the system tray. 
retval = Shell_NotifyIcon (NIM_DELETE, nid) 








Make the old window procedure the current window procedure. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
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End Sub 


Category 
Shell 


Back to the Function list. 
Back to the Reference section. 
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ShellExecute Function 








Declare Function ShellExecute Lib "shel132.d11" Alias "ShellExecuteA" (ByVal hwnd 
As Long, ByVal lpOperation As String, ByVal lpFile As String, ByVal lpParameters As 
String, ByVal lpDirectory As String, ByVal nShowCmd As Long) As Long 























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ShellExecute opens, prints, or executes a file using the Windows shell. When working with a non-executable file, the file is 
opened using its associated program. ShellExecute can also open Windows Explorer windows. The function returns 
immediately after opening the file, starting the program, or performing whatever other action was specified. 


Return Value 


If successful, the function returns a handle to the instance of the application which the function started. If an error occured, 





the function returns either 0 (indicating a lack of memory) or one of the following flags: 


ERROR_BAD_FORMAT 

The specified executable file was somehow invalid. 
SE_ERR_ACCESSDENIED 

Access was denied. 
SE_ERR_ASSOCINCOMPLETE 

The filename association is either incomplete or invalid. 
SE_ERR_DDEBUSY 

The DDE action could not run because other DDE actions are in process. 
SE_ERR_DDEFAIL 

The DDE transaction failed. 
SE_ERR_DDETIMEOUT 

The DDE transaction was not completed because the request timed out. 
SE_ERR_DLLNOTFOUND 

A required DLL file could not be found. 
SE_ERR_FNF 

The file could not be found. 
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SE_ERR_NOASSOC 

There is no program associated with the specified type of file. 
SE_ERR_OOM 

Windows has insufficient memory to perform the operation. 
SE_ERR_PNF 

The path could not be found. 
SE_ERR_SHARE 

A sharing violation occured. 


Visual Basic-Specific Issues 


None. 


Parameters 


hwnd 
A handle to the window calling the function. 
lpOperation 
The operation to perform on /pFile. This can be one of the following strings, although other options are possible, 
depending on the file being acted upon: 
"explore" 
If [pFile is a path name, open it in a Windows Explorer window. 
"open" 
Open /pFile using its associated program. Opening an executable file runs it. This is the default action if none 
is specified. 
"print" 
Print /pFile using its associated program. 
lpFile 
The name of the file to open, print, execute, or whatever is specified by /pVerb. 
lpParameters 
Additional parameters to use to perform the action. This would typically be additional command-line options to use, 
especially when running an executable file. 
lpDirectory 
The path name of the working directory to use. If this is not specified, the current directory is used. 
nShow 
One of the following flags specifying how to display any window that might be opened: 
SW_HIDE 
Hide the opened window. 
SW_MAXIMIZE 
Maximize the opened window. 
SW_MINIMIZE 
Minimize the opened window. 
SW_RESTORE 
Restore the opened window (not maximized nor minimized). 
SW_SHOW 
Show the opened window. 
SW_SHOWMAXIMIZED 
Show the opened window maximized. 
SW_SHOWMINIMIZED 
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Show the opened window minimized. 
SW_SHOWMINNOACTIVE 

Show the opened window minimized but do not activate the it. 
SW_SHOWNA 

Show the opened window in its current state but do not activate it. 
SW_SHOWNOACTIVATE 

Show the opened window in its most recent size and position but do not activate it. 
SW_SHOWNORMAL 

Show the opened window and activate it (as usual). 


Constant Definitions 
































Const ERROR BAD FORMAT = 11 

Const SK _ERR_ACCESSDENIED = 5 
Const SHE_ERR_ASSOCINCOMPLETE = 27 
Const SE_ERR_ DDEBUSY = 30 

Const SE_ERR DDEFAIL = 29 

Const SE_ERR_ DDETIMEOUT = 28 








Const SE_ERR_DLLNOTFOUND = 32 
Const SEH_ERR_FNF = 2 

Const SE _ERR_NOASSOC = 31 
Const SE_ERR_OOM = 8 










































































Const SE_ERR_PNF = 3 

Const SE_ERR_SHARE = 26 
Const SW_HIDE = 0 

Const SW_MAXIMIZE = 3 

Const SW_MINIMIZE = 6 

Const SW_RESTORE = 9 

Const SW_SHOW = 5 

Const SW_SHOWMAXIMIZED = 3 
Const SW_SHOWMINIMIZED = 2 
Const SW_SHOWMINNOACTIVE = 7 
Const SW_SHOWNA = 8 

Const SW_SHOWNOACTIVATE = 4 
Const SW_SHOWNORMAL = 1 


Example 


Use ShellExecute to perform the following tasks automatically: 


1. Run the program "C:\MyProg\startup.exe” with the "-fast" command line, in a maximized window. 
2. Open the file "C:\Project\nucleus.doc" with its associated program, in a restored window. 
3. Print the file "C:\Project\picture.bmp" via its associated program. 


The example begins each task immediately and then finishes -- it does not wait for any of these three tasks to complete. The 
example runs when button Command] is clicked. Naturally, to run this example, you must create a command button named 
Command! on form window Form1. 
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' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function ShellExecute Lib "shel1l32.d1l1l" Alias "ShellExecuteA" (ByVal 

hwnd As Long, _ 
ByVal lpOperation As String, ByVal lpFile As String, ByVal lpParameters As 

String, ByVal _ 

lpDirectory As String, ByVal nShowCmd As Long) As Long 

Public Const SW_MAXIMIZE = 3 

Public Const SW_MINIMIZE = 6 

Public Const SW_RESTORE = 9 






























































kkk 





' Place the following code inside window Forml. 


Private Sub Command1_Click () 
Dim retval As Long ' return value 








' 1. Run the program: 
retval = ShellExecute(Forml.hWnd, "open", "C:\MyProg\startup.exe", "-fast", 


"C:\MyProg\", 





SW_MAXIMIZE) 
' 2. Open the document: 
retval = ShellExecute(Forml.hWnd, "open", "C:\Project\nucleus.doc", 
"Cs\ Project \", 











wee 
A 


SW_RESTORE) 
' 3. Print the document (minimized in case a window opens): 
retval = ShellExecute(Forml.hWnd, "print", "C:\Project\picture.bmp", 
"Cs \Projecty"; 


wee 
i 





SW_MINIMIZE) 














End Sub 


See Also 


ShellExecuteEx 





Category 
Shell 


Go back to the Function listing. 
Go back to the Reference section index. 








Last Modified: August 26, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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ShellExecuteEx Function 


Declare Function ShellExecuteEx Lib "shel1l32.d11" Alias "ShellExecuteExA" 
(lpExecInfo As SHELLEXECUTEINFO) As Long 




















Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Required Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


ShellExecuteEx opens, prints, or executes a file using the Windows shell. When working with a non-executable file, the file 
is opened using its associated program. ShellExecuteEx can also open Windows Explorer windows. The function returns 
immediately after opening the file, starting the program, or performing whatever other action was specified. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns zero (use GetLastError to get the 
error code). 


Visual Basic-Specific Issues 


None. 


Parameters 


IpExecInfo 
Information describing the action to perform through the Windows shell. After the function call completes, this 
structure also receives information about the function's result. 


Example 


Open the file "C:\Docs\readme.txt" using whatever program is associated with *.txt files (by default, Notepad). Wait until the 
user has closed the window before continuing with the example. The example begins when the user clicks button Command 1. 
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Obviously, to use this example, you need to place a command button named Command! on a form window. 





(Copy them to 


This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 





the (declarations) section of a module.) 





Public Type SHEI 





iLEXECUTEINFO 








cbSize As Long 
fMask As Long 


hwnd As 





Long 


lpVerb As String 
lpFile As String 
lpParameters As String 
lpDirectory As String 


nShow As Long 
hiIinstApp As Long 





lpClass 





lpIDList As Long 


As String 


hkeyClass As Long 
dwHotKey As Long 


hicon As Long 





hProcess As Long 


End Type 


Public Const SEE MASK NOCLOSEPROCESS = &H40 
Public Const SW_SHOWNORMAL = 1 
Public Declare Function ShellExecuteEx Lib "shel132.dl11" Alias "ShellExecuteExA" 
(lpExecInfo As _ 
SHELLEXECUTEINFO) As Long 

















Public Const SE_ERR_FNF = 2 
Public Const SE_ERR_NOASSOC = 31 
Public Declare Function WaitForSingleObject Lib "kernel32.d1l1" (ByVal hHandle As 








Long, ByVal 








dwMilliseconds As Long) As Long 
Public Const INFINITE = &HFFFF 











Public Const WAI 


' xxx Place the 


T_TIMEOUT = &H102 








eons 


ollowing code inside window Forml. *** 








Private Sub Command1_Click () 

















Dim sei As SHELLEXECUTEINFO ' structure used by the function 
Dim retval As Long ' return value 

' Load the information needed to open C:\Docs\readme.txt 

" into the structure. 

With sei 


Size of the structure 

.cbSize = Len (sei) 

' Use the optional hProcess element of the structure. 
.fMask = SEE MASK NOCLOSEPROCESS 

" Handle to the window calling this function. 

-hwnd = Forml.hWnd 

' The action to perform: open the fil 
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-lpVerb = "open" 

' The file to open. 

.lpFile = "C:\Docs\readme.txt" 

' No additional parameters are needed her 

.lpParameters = "" 

" The default directory -= not really necessary in this case. 
.lpDirectory = "C:\Docs\" 

' Simply display the window. 

-nShow = SW_SHOWNORMAL 

' The other elements of the structure ar ither not used 
' or will be set when the function returns. 


End With 


' Open the fil 











using its associated program. 





retval = ShellExecuteEx (sei) 
If retval = 0 Then 


' The fu 
t could 





nection failed, so report the error. Err.LastDllError 
also be used instead, if you wish. 





Select Case sei.hInstApp 


m 


Case SE 





ERR_FNF 
Debug.Print "The file C:\Docs\readme.txt was not found." 





Case SE_NOASSOC 





Debug.Print "No program is associated with *.txt files." 





Case Else 
Debug.Print "An unexpected error occured." 
End Select 
Else 
' Wait for the opened process to close before continuing. Instead 


' of waiting once for a time of INFINITE, this example repeatedly 


checks to see if the 











' is still open. This allows the DoEvents VB function to be called, 








preventing 
' our program from appearing to lock up while it waits. 
Do 
DoEvents 
retval = WaitForSingleObject (sei.hProcess, 0) 
Loop While retval = WAIT_TIMEOUT 
Debug.Print "Notepad (or whatever program was opened) has just 
closed." 
End If 
End Sub 


See Also 


ShellExecute 


Category 


Shell 
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Back to the Function list. 
Back to the Reference section. 
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SHEmptyRecycleBin Function 


Declare Function SHEmptyRecycleBin Lib "shel1l32.d11" Alias 
"SHEmptyRecycleBinA" (ByVal hwnd As Long, ByVal pszRootPath As String, 
ByVal dwFlags As Long) As Long 


Platforms 


e Windows 95: Requires Internet Explorer 4.0 or later with integrated shell installed. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 4.0 or later and Internet Explorer 4.0 or later with integrated 
shell installed. 

e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


SHEmptyRecycleBin deletes the contents of the Recycle Bin, displaying dialog boxes as desired. The 
function can empty the Recycle Bin of a particular drive, or it can empty all Recycle Bins as a whole. 


Return Value 

If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 
Visual Basic-Specific Issues 

None. 


Parameters 


hwnd 
A handle to the window calling the function. This window will be the owner of any dialog boxes the 


function uses. 
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pszRootPath 
A path belonging to the drive to empty the Recycle Bin of (this doesn't have to be the root path). To 
empty all Recycle Bins as a whole, set this to an empty string. 
dwFlags 
A combination of zero or more of the following flags specifying additional options: 
SHERB_NOCONFIRMATION 
Do not display a confirmation prompt for the user. 
SHERB_NOPROGRESSUI 
Do not display the dialog box displaying the progress of emptying the Recycle Bin. 
SHERB_NOSOUND 
Do not play the Empty Recycle Bin sound after the contents of the Recycle Bin are deleted. 


Constant Definitions 


Const SHERB_NOCONFIRMATION = &H1 
Const SHERB_NOPROGRESSUI = &H2 
Const SHERB_NOSOUND = &H4 





Example 


' This code is licensed according to the terms and conditions listed here. 


" Delete the contents in the system's Recycle Bin, without 





' showing the progress dialog. If an error occurs, be safe and 
' make sure the proper Recyle Bin icon is used. 
Dim retval As Long ' return value 


" Delete the contents of the system's Recycle Bin, if the user OKs it. 
retval = SHEmptyRecycleBin(Forml.hWnd, "", SHERB_NOPROGRESSUT) 











' If an error occured, be overly save and refresh the Recycle Bin 
' icon. This probably isn't necessary, however. 
If retval <> 0 Then ' error 
retval = SHUpdateRecycleBinIcon () 
End If 








See Also 


SHQueryRecycleBin, SHUpdateRecycleBinIcon 


Category 
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Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 
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SHFileOperation Function 


Declare Function SHFileOperation Lib "sShell32.d11" Alias "SHFileOperationA" (lpFileOp 
As Byte) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SHFileOperation copies, moves, renames, or deletes an object in the file system. Instead of performing the action silently as 
regular file API functions do, SHFileOperation uses the dialog box prompts of the shell. This function is also the proper way 
to send one or more files to the Recycle Bin instead of deleting them outright. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


Although /pFileOp is technically a SHFILEOPSTRUCT structure passed to SHFileOperation, a byte array must be used. This 
is because of a byte alignment quirk in Visual Basic that results in misplacing some data in the structure. Note the code used in 
the example to fix the problem. For more information about the reason for this, consult the SHFILEOPSTRUCT structure's 


page. 





Parameters 
lpFileOp 


A SHFILEOPSTRUCT structure, copied properly into a byte array, that specifies the file operation to perform. It may 
also receive some feedback from the function. 


Example 


When the user clicks button cmdDelete, send all the files inside C:\Stuff\ to the Recycle Bin. Prompt the user as necessary. To 
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use this example, place a command button named cmdDelete on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type SHFILEOPSTRUCT 

hwnd As Long 

wFunc As Long 

pFrom As String 

pTo As String 
fFlags As Integer 
fAnyOperationsAborted As Long 

hNameMappings As Long 

lpszProgressTitle As String 
End Type 



































(lpFileOp As Byte) As Long 
Public Const FO_DELETE = &H3 

ublic Const FOF_ALLOWUNDO = &H40 
ublic Const FOF_FILESONLY = &H80 























AG) 




















AG) 








' xxx Place the following code inside the form window. *** 


Private Sub cmdDelete Click () 








Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" _ 
(Destination As Any, Source As Any, ByVal Length As Long) 
Public Declare Function SHFileOperation Lib "shel1l32.d1l1" Alias "SHFileOperationA" _ 
































' Load the proper parameters into the structure. 
With fos 
' The window invoking the file operation. 
-hwnd = Forml.hWnd 
' Delete the specified files. 
-wFunc = FO_DELETE 
' The list of files to delete. 






































Dim fos As SHFTLEOPSTRUCT ' structure to pass to the function 
Dim sa(l To 32) As Byte ' byte array to make structure properly sized 
Dim retval As Long ' return value 


-pFrom = "C:\Stuff\*.*" & vbNullChar & vbNullChar 
' Target information isn't needed for deletion of files. 





.pTo = vbNullChar & vbNullChar 
' Allow Undo (i.e., send to Recycle Bin on 








subfolders. 





-fFlags = FOF_ALLOWUNDO Or FOF_FILESONLY 























.fAnyOperationsAborted = 0 
-hNameMappings = 0 
loszProgressTitle = vbNullChar 








End With 








' Transfer the contents of the structure object int 





delete), and do not delete 


The rest of the structure isn't needed for this example. 


to the byte 





' array in order to compensate for a byte alignmen 
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CopyMemory sa(1), fos, LenB (fos) 
CopyMemory sa(19), sa(21), 12 











' Send those files to the Recycle Bin. 
retval = SHFileOperation (sa (1) ) 





' Although not necessary for this example, transfer the (possibly changed) 
' byte array back into the structure. This would be necessary in case 
SHFileOperation might 
' have placed some feedback information into the structure passed to it. 
CopyMemory sa(21), sa(19), 12 
CopyMemory fos, sa(l1), Len (fos) 
End Sub 




















Category 
Shell 


Back to the Function list. 
Back to the Reference section. 


Last Modified: December 17, 2000 
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SHFreeNameMappings Function 








Declare Sub SHFreeNameMappings Lib "shell32.d11" (ByVal hNameMappings As Long) 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SHFreeNameMappings frees a file mapping object created by the SHFileOperation function. The file mapping object consists 
of an array of SHNAMEMAPPING structures identifying the renamed files. 





Return Value 


SHFreeNameMappings does not return a value. 


Visual Basic-Specific Issues 


NOTE: Although I know how to create and free a file mapping object, I still have not been able to figure out how to actually 
access its contents. If you know how to do this, please e-mail me. 


Parameters 


hNameMappings 
A handle to the file mapping object to free. 


Example 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Type SHFILEOPSTRUCT 


hwnd As Long 
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wFunc As Long 

pFrom As String 

pTo As String 

fFlags As Integer 
fAnyOperationsAborted As Long 
hNameMappings As Long 
lpszProgressTitle As String 











End Type 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" _ 











(Destination As Any, Source As Any, ByVal Length As Long) 

Public Declare Function SHFileOperation Lib "sShell32.d11" Alias "SHFileOperationA”" _ 
(lpFileOp As Byte) As Long 

ublic Declare Sub SHFreeNameMappings Lib "shel132.d1l1" (ByVal hNameMappings As Long) 
ublic Const FO_COPY = &H2 

ublic Const FOF_ALLOWUNDO = &H40 

ublic Const FOF_FILESONLY = &H80 

ublic Const FOF_WANTMAPPINGHANDLE = &H20 












































w g UU 'U td 




















' Copy the files "C:\Folder\*.*" to the folder "C:\NewFolder\". 
































Dim fos As SHFILEOPSTRUCT ' structure to pass to the function 
Dim s(1 To 24) As Byte ' byte array to make structure properly sized 
Dim retval As Long " return value 








' Load the proper parameters into the structure. 
With fos 
' The window invoking the file operation. 
-hwnd = Forml.hwnd 
' Copy the specified files. 
-wFunc = FO COPY 
' The list of source files to copy. 

















.pFrom = "C:\Folder\*.*" & vbNullChar & vbNullChar 
' The path to copy the files to. 
.pTo = "C:\NewFolder\" & vbNullChar & vbNullChar 


' Allow Undo, and do not copy subfolders. 

' Also ask for a file mapping object. 

.fFlags = FOF_ALLOWUNDO Or FOF_FILESONLY Or FOF_WANTMAPPINGHANDLI 
' The rest of the structure isn't needed for this example. 
.fAnyOperationsAborted = 0 

-hNameMappings = 0 

lpszProgressTitle = vbNullChar 














ira 


























End With 











' Transfer the contents of the structure object into the byte 
' array in order to compensate for a byte alignment problem. 
CopyMemory sa(l1), fos, LenB(fos) 

CopyMemory sa(19), structarray(21), 12 




















' Send those files to the Recycle Bin. 
retval = SHFileOperation(sa(1)) 








i 








Transfer the byte array back into the structure. This is necessary 
' because the mapping handle has been added to the structure. 


http://216.26.168.92/vbapi/ref/s/shfreenamemappings.html (2 of 3) [9/1/2002 5:48:08 PM] 


http://216.26.168.92/vbapi/ref/s/shfreenamemappings.htm] 


CopyMemory sa(21), sa(19), 12 
CopyMemory fos, sa(l), Len(fos) 








F 


If you knew how to access the file mapping object, it would be done her 











' Free the file mapping object to free up resources. 
SHFreeNameMappings fos.hNameMappings 


Category 
Shell 


Back to the Function list. 
Back to the Reference section. 


Last Modified: April 16, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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SHGetFilelnfo Function 


Declare Function SHGetFileInfo Lib "Shel1l32.d11" Alias "SHGetFileInfoA" (ByVal 
pszPath As Any, ByVal dwFileAttributes As Long, psfi As SHFILEINFO, ByVal 
cbFileInfo As Long, ByVal uFlags As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


SHGetFileInfo retrieves information about a file system object in the shell. Such file system objects include files, 
directories, virtual folders, and drives. The information retrieved generally relates to how the object appears in the 


system shell. 


Return Value 


If the uFlags parameter contains the SHGFI_LEXETYPE flag, the function returns a value identifying the type of the 
executable file. If both the low-order and high-order words are not zero, the file is a Windows application. If only the 
low-order word is not zero but the high-order word is zero, the file is an MS-DOS based program or batch file or a 32- 
bit Windows console application. If the entire return value is zero, an error occured. 


If the uFlags parameter instead contains the SHGFI_S YSICONINDEX flag, the function returns a handle to an 
internal image list which contains the icon requested by the function. If this value is zero, an error occured. 


If neither of those two flags are specified, the return value is a non-zero value if successful, or zero if an error 
occured. 


Visual Basic-Specific Issues 


None. 
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Parameters 


pszPath 
The name of the file, directory, or drive to retrieve information about. If uFlags contains the SHGFI_PIDL 
flag, this is instead a pointer to an ITEMIDLIST structure (a PIDL) identifying a file system object. If uFlags 
contains the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to refer to an actual file; the 
function will instead retrieve attributes which the file would have if it existes (such as information relating to 
its extension). 
dwFileAttributes 
If uFlags contains the SHGFI_USEFILEATTRIBUTES flag, this parameter is a combination of the following 
flags specifying the file attributes of the theoretical file. If that flag is not specified, this parameter is ignored. 
FILE_ATTRIBUTE_ARCHIVE 
An archive file (which most files are). 
FILE_ATTRIBUTE_COMPRESSED 
A file residing in a compressed drive or directory. 
FILE_ATTRIBUTE_DIRECTORY 
A directory instead of a file. 
FILE_ATTRIBUTE_HIDDEN 
A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL 
An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY 
A read-only file. 
FILE_ATTRIBUTE_SYSTEM 
A system file, used exclusively by the operating system. 
psfi 
The structure that receives information about the file. 
cbFileInfo 
The size in bytes of the structure passed as psfi. 
uF lags 
A combination of the following flags specifying what information to retrieve about the file system object: 
SHGFI_ATTRIBUTES 
Retrieve the attributes of the file system object and put that information into the structure. 
SHGFI_DISPLAYNAME 
Retrieve the display name of the file system object. This is its full name as presented in the system 
shell. 
SHGFI_LEXETYPE 
Retrieve what type of executable file was passed to the function. The result is returned by the function. 
This flag cannot be used with any other flags. 
SHGFI_ICON 
Retrieve a handle to the icon used to depict the file system object and put it into the structure. After 
using the handle, your program must use Destroylcon to free up resources. 
SHGFI_ICONLOCATION 
Retrieve the name of the file which holds the icon used to depict the file system object and put it into 
the structure. 
SHGFI_LARGEICON 
When used with SHGFI_ICON, causes the function to retrieve the file system object's large icon. 
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SHGFI_LLINKOVERLAY 
When used with SHGFI_ICON, causes the function to add the link overlay (the "shortcut arrow" in the 
bottom right corner) to the icon. 
SHGFI_OPENICON 
When used with SHGFI_ICON, causes the function to use the icon which depicts the file system object 
as being open. (This usually applies only to icons used to depict folders or directories.) 
SHGFI_PIDL 
Indicates that pszPath contains a PIDL instead of a filename. 
SHGFI_SELECTED 
When used with SHGFI_ICON, causes the function to add the tint of the system highlight color to the 
file system object's icon (making it look "selected"). 
SHGFI_SHELLICONSIZE 
When used with SHGFI_ICON, causes the function to retrieve a shell-sized icon instead of the standard 
size of icon. 
SHGFI_SMALLICON 
When used with SHGFI_ICON, causes the function to retrieve the file system object's small icon. 
SHGFI_SYSICONINDEX 
Retrieve the index of the icon in an internal image list and place it into the structure. The function 
returns a handle to the image list itself. Note that trying to access any icon with an index not equal to 
the one placed inside the structure will cause unexpected results! 
SHGFI_TYPENAME 
Retrieve the name of the file type of the file system object and place it into the structure. 
SHGFI_USEFILEATTRIBUTES 
Instead of specifying a file that actually exists, pszPath gives the name of a possibly ficticious file and 
dwFileAttributes identifies the pretend file's attributes. The function then behaves as if the file did exist 
and retrieves the appropriate information. This flag cannot be used with the SHGFI_LATTRIBUTES, 
SHGFI_EXETYPE, or SHGFI_PIDL flags. 


Constant Definitions 




































































Const FILE ATTRIBUTE ARCHIVE = &H20 
Const FILE ATTRIBUTE COMPRESSED = &H800 
Const FILE ATTRIBUTE DIRECTORY = &H10 
Const FILE ATTRIBUTE HIDDEN = &H2 
Const FILE ATTRIBUTE NORMAL = &H0O 
Const FILE ATTRIBUTE READONLY = &H1 
Const FILE ATTRIBUTE SYSTEM = &H4 
Const SHGFI_ATTRIBUTES = &H800 

Const SHGFI_DISPLAYNAME = &H200 

Const SHGFI_EXETYPE = &H2000 

Const SHGFI_ICON = &H100 

Const SHGFI_ICONLOCATION = &H1000 
Const SHGFI_LARGEICON = &H0O 

Const SHGFI_LINKOVERLAY = &H8000 
Const SHGFI_OPENICON = &H2 

Const SHGFI_PIDL = &H8 

Const SHGFI_SELECTED = &H10000 
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Const SHGFI_SHELLICONSIZE = &H4 
Const SHGFI_SMALLICON = &H1 

Const SHGFI_SYSICONINDEX = &H4000 
Const SHGFI_TYPENAME = &H400 

Const SHGFI_USEFILEATTRIBUTES = &H10 














Example 


' This code is licensed according to the terms and conditions listed here. 


' Retrieve information about a generic MP3 file found in the system 

' shell. The file specified by the function does not actually exist, 
' but its properties will reflect what any MP3 file would probably 

' have (the .mp3 extension and the "archive" attribute). 

Dim info As SHFILEINFO ' receives information about the file 





Dim retval As Long ' return value of the function 


£ Ea 


' Retrieve information about what the C:\dummy.mp3 file would 
' look like if it existed. 
retval = SHGetFileInfo("C:\dummy.mp3", FILE_ATTRIBUTE_ARCHIVE, info, Len (info), 
SHGFI_USEFILEATTRIBUTES Or SHGFI_TYPENAME Or SHGFI_ICON) 




















E a 


' Display the name of the .mp3 file type on the computer. 

' (Note how the trailing nulls are removed from the string.) 
Debug.Print "The file type of .mp3 files is "; Left (info.szTypeName, 
InStr(info.szTypeName, vbNullChar) - 1) 








' Draw the icon used for MP3 files in the corner of window Forml. 
retval = Drawlcon(Forml.hDC, 0, 0, info.hIcon) 

' Destroy the icon handle to save resources. 

retval = DestroyIcon(info.hIcon) 





Category 


Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: December 22, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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This page is at http://www.vbapi.com/ref/s/shgetfileinfo.html 


http://216.26.168.92/vbapi/ref/s/shgettileinfo.html (5 of 5) [9/1/2002 5:48:18 PM] 


http://216.26.168.92/vbapi/ref/s/shgetfolderlocation.htm] 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





SHGetFolderLocation Function 


Declare Function SHGetFolderLocation Lib "Shel1l32.d11" Alias "SHGetFolderLocationA" 
(ByVal hwndOwner As Long, ByVal nFolder As Long, ByVal hToken As Long, ByVal 
dwReserved As Long, ppidl As Long) As Long 























Platforms 


Windows 95: Not Supported. 
Windows 98: Not Supported. 
Windows NT: Not Supported 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Note: SHGetFolderLocation may be available on platforms other than Windows 2000. It also appears in shfolder.dll, a 
redistributable DLL. The Declare for that function is identical to the one above, except for the filename. shfolder.dll is not 
necessarily guaranteed to be on a system. 


Description & Usage 


SHGetFolderLocation creates a pointer to an ITEMIDLIST structure (a.k.a. a PIDL) refering to a special folder on the 
computer. The PIDL can refer to special folders which are either a physical path on a drive or a virtual folder. After your 
program is finished using the PIDL obtained by this function, use CoTaskMemFree to release it. 





Return Value 


The function returns one of the following flags: 


S_OK 

The function completed successfully. 
S_FALSE 

The CSIDL of the special folder is valid but is a virtual folder. 
E_INVALIDARG 

The CSIDL is not valid. 





Visual Basic-Specific Issues 


None. 


Parameters 
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hwndOwner 


A handle to the window calling the function. This window will own any dialog boxes created by this function. 


nFolder 


The CSIDL of the special folder to get a PIDL to. 


hToken 


A token identifying the user. This is normally 0, but may be other values for security purposes. 


dwReserved 


Reserved -- set to 0. 


ppidl 
Receives a PIDL to 


Example 


F 





' Open the 
' the actual 
Computer 
' may be selected. 


name 





the desired special folder. 





of the folder 








(if it 





Dim bi As 
pidl As Long 

physpath As St 
retval As Long 








Dim 





Dim 
Dim 

















' Initialize the s 
bi.hwndOwner = 
' Specify the My C 
retval = 
' Make room in the 
.pszDisplayName 











BROWSEIN 


FO ' structure passed 








' PIDL to the user's selection 





ring ' string used to 


" return value 


tructure to be passed to the func 
Forml.hWnd ' 


window Forml is 








temporarily hold 

















= Space (260) 
































omputer virtual folder as the root 
SHGetFolderLocation (Forml.hWnd, CSIDL_ DRIVES, 
buffer to get the [virtual] 





bi.lpszTitle = "Please choose a folder." ' 
bi.ulFlags = 0 ' no flags are needed here 
bi.lpfn = 0 ' no callback function is being used 
bi.lParam = 0 ' not needed 

bi.iImage = 0 ' this will be set by the function 
' Open the Browse for Folder dialog box. 

pidl = SHBrowseForFolder (bi) 














" Tf the user sel 








' and its physical 


cted something, 
location on the system. 





If pidl <> 0 Then 
' Remove th 








bi.pszDisplayName = 


L) 








Left (bi.pszDisplayName, 








Debug.Print "Th 











physpath = 
retval = 


Space 


the folder is not a virtual 





user selected: "; 
folder, 








(260) ' 

















If retval = 
Debug.Print 








Location: (virtual 





bi.pszDisplayName 

display its physical location. 
make room in the buffer 
SHGetPathFromIDList (pidl, 
0 Then 
"Physical 





physpath) 


folder)" 
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folder). 


to the function 


tion. 
the owner of 





O, O, 


display its display name 


mpty space from the display name variable. 
InStr(bi.psz 





Any 


DisplayName, 


This code is licensed according to the terms and conditions listed here. 


Browse for Folder dialog box and display both the display name and 
is not a virtual 





folder under My 


the physical path 


the dialog box 


bi.pidlRoot) 
folder's display name 


Message displayed to the user 


vbNullChar) - 
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Else 
' Remove th mpty space and display the result. 
physpath = Left(physpath, InStr(physpath, vbNullChar) - 1) 
Debug.Print "Physical Location: "; physpath 

End If 





' Free the pidl returned by the function. 
CoTaskMemFree pidl 
End If 











' Whether successful or not, free the PIDL which was used to 
' identify the My Computer virtual folder. 
CoTaskMemFree bi.pidlRoot 

















See Also 


SHGetFolderPath, SHGetSpecialFolderLocation 


Category 
Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: September 26, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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SHGetPathFromIDList Function 


Declare Function SHGetPathFromIDList Lib "shel132.d1l1" Alias "SHGetPathFromIDListA" 
(ByVal pidl As Long, ByVal pszPath As String) As Long 























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SHGetPathFromIDList determines the path of the folder refered to by a pointer to an ITEMIDLIST structure (a.k.a. a PIDL). 
The function only works if the PIDL refers to a physical directory on the system; it cannot get the name of a virtual folder. 


Return Value 


If an error occured or the PIDL refers to a virtual folder, the function returns 0. If successful, the function returns a non-zero 
value. 


Visual Basic-Specific Issues 


None. 


Parameters 
pidl 


The PIDL to determine the physical path of, if it is not a virtual folder. 


pszPath 
Receives a null-terminated string holding the path which the PIDL identifies. The string passed initially to the function 


must be at least 260 characters long. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' Open the Browse for Folder dialog box and display both the display name and 



























































" the actual name of the folder (if it is not a virtual folder). Any folder under My 
Computer 

' may be selected. 

Dim bi As BROWSEINFO ' structure passed to the function 

Dim pidl As Long ' PIDL to the user's selection 
Dim physpath As String ' string used to temporarily hold the physical path 
Dim retval As Long ' return value 

' Initialize the structure to be passed to the function. 





bi.hwndOwner = Forml.hWnd ' window Forml is the owner of the dialog box 
' Specify the My Computer virtual folder as the root 
retval = SHGetSpecialFolderLocation (Forml.hWnd, CSIDL_DRIVES, bi.pidlRoot) 





















































' Make room in the buffer to get the [virtual] folder's display name 
bi.pszDisplayName = Space (260) 

bi.lpszTitle = "Please choose a folder." ' Message displayed to the user 
bi.ulFlags = 0 ' no flags are needed her 

bi.lpfn = 0 ' no callback function is being used 

bi.lParam = 0 ' not needed 

bi.iImage = 0 ' this will be set by the function 








' Open the Browse for Folder dialog box. 
pidl = SHBrowseForFolder (bi) 














' If the user selected something, display its display name 
' and its physical location on the system. 
If pidl <> 0 Then 
' Remove th mpty space from the display name variable. 
bi.pszDisplayName = Left (bi.pszDisplayName, InStr(bi.pszDisplayName, vbNullChar) - 
1) 





























Debug.Print "The user selected: "; bi.pszDisplayName 

' If the folder is not a virtual folder, display its physical location. 
physpath = Space (260) ' make room in the buffer 

retval = SHGetPathFromIDList (pidl, physpath) 





















































If retval = 0 Then 
Debug.Print "Physical Location: (virtual folder)" 
Else 
' Remove the empty space and display the result. 
physpath = Left (physpath, InStr(physpath, vbNullChar) - 1) 
Debug.Print "Physical Location: "; physpath 
End If 





' Free the pidl returned by the function. 
CoTaskMemFree pidl 
End If 




















' Whether successful or not, free the PIDL which was used to 
' identify the My Computer virtual folder. 
CoTaskMemFree bi.pidlRoot 














Category 


Shell 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: September 25, 1999 
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SHGetFolderPath Function 


Declare Function SHGetFolderPath Lib "sShell132.d11" Alias "SHGetFolderPathA" (ByVal 
hwndOwner As Long, ByVal nFolder As Long, ByVal hToken As Long, ByVal dwFlags As 
Long, ByVal lpszPath As String) As Long 











Platforms 


Windows 95: Not Supported. 
Windows 98: Not Supported. 
Windows NT: Not Supported. 
Windows 2000: Supported. 
Windows CE: Not Supported. 


Note: SHGetFolderPath may be available on platforms other than Windows 2000. It also appears in shfolder.dll, a 
redistributable DLL. The Declare for that function is identical to the one above, except for the filename. shfolder.dll is not 
necessarily guaranteed to be on a system. 


Description & Usage 


SHGetFolderPath retrieves the name of the path of a special folder on the system. This function only works with special 
folders which are physical directories on a disk. The function will fail if the special folder is a virtual folder. 


Return Value 


The function returns one of the following flags: 
S_OK 
The function completed successfully. 
S_FALSE 
The CSIDL of the special folder is valid but is a virtual folder. 


E_INVALIDARG 
The CSIDL is not valid. 


Visual Basic-Specific Issues 


None. 


Parameters 


http://216.26.168.92/vbapi/ref/s/shgetfolderpath.html (1 of 3) [9/1/2002 5:49:02 PM] 


Windows API Guide: SHGetFolderPath Function 


hwndOwner 
A handle to the window calling the function, which will own any dialog boxes the function may create. 
nIndex 
The CSIDL of the special folder to get the path of. 
hToken 
A token identifying the user. This is normally 0, but may be other values for security purposes. 
dwFlags 
One of the following flags specifying which path to retrieve: 
SHGFP_TYPE_CURRENT 
Retrieve the folder's current path. 
SHGFP_TYPE_DEFAULT 
Retrieve the folder's default path. 
IpszPath 
Receives a null-terminated string holding the path name of the special folder. A string at least 260 characters long 
must be passed as this parameter to receive the result. 


Constant Definitions 


Const S_OK = &H0O 

Const S_FALSE = &H1 

Const E_INVALIDARG = &H80070057 
Const SHGFP_TYPE CURRENT = 0 
Const SHGFP_TYPE DEFAULT 1 














Example 


This code is licensed according to the terms and conditions listed here. 


' Display the path of the directory used as the My Documents 

' special folder. This might not be "C:\My Documents" if the user renamed it! 
Dim pathname As String ' receives the path of My Documents 

Dim retval As Long ' return value 

















' Make enough room in the buffer to receive the string. 

pathname = Space (260) 

' Get the path name of the My Documents special folder 

retval = SHGetolderPath (Forml.hWnd, CSIDL_PERSONAL, 0, SHGFP_TYPE_CURRENT, pathname) 
' Remove th mpty space from the string. 

pathname = Left (pathname, InStr (pathname, vbNullChar) - 1) 

' Display the result. 

Debug.Print "The My Documents special 





























Fs 


older is: "; pathname 





See Also 


SHGetFolderLocation, SHGetSpecialFolderPath 





Category 
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Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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SHGetSpecialFolderLocation Function 





Declare Function SHGetSpecialFolderLocation Lib "shell32.d1ll1" (ByVal hwndOwner As 
Long, ByVal nFolder As Long, ppidl As Long) As Long 











Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 

Windows 2000: Supported but Obsolete; use SHGetFolderLocation instead. 
e Windows CE: Not Supported. 





Description & Usage 


SHGetSpecialFolderLocation creates a pointer to an ITEMIDLIST structure (a.k.a. a PIDL) refering to a special folder on the 
computer. The PIDL can refer to special folders which are either a physical path on a drive or a virtual folder. After your 
program is finished using the PIDL obtained by this function, use CoTaskMemFree to release it. 





Return Value 


If successful, the function returns zero. If an error occured, the function returns an error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


hwndOwner 

A handle to the window calling the function. This window will own any dialog boxes created by this function. 
nFolder 

The CSIDL of the special folder to get a PIDL to. 


ppidl 
Receives a PIDL to the desired special folder. 


Example 


Open the Browse for Folder dialog box and display both the display name and the actual name of the folder (unless it is a 
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virtual folder). Any folder under My Computer may be selected. To run this example, place a command button named 
Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SHGetSpecialFolderLocation Lib "sShell32.dl1" (ByVal hwndOwner 


As Long, 

















ByVal nFolder As Long, ppidl As Long) As Long 
Public Const CSIDL_ DRIVES = &H11 
Public Type BROWSEINFO 
hwndOwner As Long 
pidlRoot As Long 
pszDisplayName As String 
lpszTitle As String 
ulFlags As Long 
lpfn As Long 
lParam As Long 
iImage As Long 


















































End Type 
Public Declare Function SHBrowseForFolder Lib "shell32.d11" Alias 
"SHBrowseForFolderA" _ 
(lpbi As BROWSEINFO) As Long 
Public Declare Function SHGetPathFromIDList Lib "shel1l132.d1l1" Alias 


"SHGetPathFromIDListA" _ 
(ByVal pidl As Long, ByVal pszPath As String) As Long 





































































































Public Declare Sub CoTaskMemFree Lib "ole32.d11" (ByVal pv As Long) 
' *** Place the following code inside a form window. *** 
Private Sub Command1_Click () 
Dim bi As BROWSEINFO ' structure passed to the function 
Dim pidl As Long ' PIDL to the user's selection 
Dim physpath As String ' string used to temporarily hold the physical path 
Dim retval As Long ' return value 

















' Initialize the structure to be passed to the function. 
With bi 





' The owner of the dialog box. 

-hwndOwner = Me.hWnd 

' Specify the My Computer virtual folder as the root. 
retval = SHGetSpecialFolderLocation (Me.hWnd, CSIDL_DRIVES, .pidlRoot) 
' Make room in the buffer to get the [virtual] folder's display name. 
-pszDisplayName = Space (260) 

' Message displayed to the user. 

-lpszTitle = "Please choose a folder." 

' Nothing else needs to be set. 

-ulFlags = 0 

-lpfn = 0 

.lParam 
.i Image 












































Il 
oo 
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End With 








" Open the Browse for Folder dialog box. 

pidl = SHBrowseForFolder (bi) 

' If the user selected something, display its display name 

' and its physical location on the system. 

If pidl <> 0 Then 
' Remove the empty space from the display name variable. 
bi.pszDisplayName = Left (bi.pszDisplayName, InStr(bi.pszDisplayName, 

















































































































vbNullChar) - 1) 
Debug.Print "The user selected: "; bi.pszDisplayName 
' If the folder is not a virtual folder, display its physical 
location. 
physpath = Space (260) 
retval = SHGetPathFromIDList (pidl, physpath) 
If retval = 0 Then 
Debug.Print "Physical Location: (virtual folder)" 
Else 
' Remove th mpty space and display the result. 
physpath = Left (physpath, InStr(physpath, vbNullChar) - 1) 
Debug.Print "Physical Location: "; physpath 
End If 
' Free the pidl returned by the function. 
CoTaskMemFree pidl 
End If 




















' Whether successful or not, free the PIDL which was used to 
' identify the My Computer virtual folder. 
CoTaskMemFree bi.pidlRoot 

End Sub 














See Also 


SHGetFolderLocation, SHGetSpecialFolderPath 


Category 
Shell 


Go back to the Function listing. 
Go back to the Reference section index. 
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SHGetSpecialFolderPath Function 


Declare Function SHGetSpecialFolderPath Lib "shell132.dl1l1" Alias 
"SHGetSpecialFolderPathA" (ByVal hwndOwner As Long, ByVal lpszPath As String, 
ByVal nFolder As Long, ByVal fCreate As Long) As Long 











Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later with Internet Explorer 4.0 or later. 
Windows 2000: Supported but Obsolete; use SHGetFolderPath instead. 


e Windows CE: Not Supported. 





Description & Usage 


SHGetSpecialFolderPath retrieves the name of the path of a special folder on the system. This function only works 
with special folders which are physical directories on a disk. The function will fail if the special folder is a virtual 


folder. 


Return Value 


If an error occured, the function returns 0. If successful, the function returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hwndOwner 
A handle to the window calling the function, which will own any dialog boxes the function may create. 
IpszPath 
Receives a null-terminated string holding the path name of the special folder. A string at least 260 characters 
long must be passed as this parameter to receive the result. 
nIndex 
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The CSIDL of the special folder to get the path of. 


fCreate 
If 0, do not create the special folder if it does not yet exist. If a non-zero value, create the special folder if it 


does not yet exist. 


Example 


' This code is licensed according to the terms and conditions listed here. 


= 


' Display the path of the directory used as the My Documents 





' special folder. This might not be "C:\My Documents" if the user renamed it! 
Dim pathname As String ' receives the path of My Documents 
Dim retval As Long ' return value 











' Make enough room in the buffer to receive the string. 

pathname = Space (260) 

' Get the path name of the My Documents special folder 

retval = SHGetSpecialFolderPath (Forml.hWnd, pathname, CSIDL_PERSONAL, 0) 
' Remove the empty space from the string. 

pathname = Left (pathname, InStr(pathname, vbNullChar) - 
' Display the result. 

Debug.Print "The My Documents special folder is: "; pathname 








L 
| 
<~ 





See Also 


SHGetFolderPath, SHGetSpecialFolderLocation 


Category 
Shell 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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ShowCursor Function 


Declare Function ShowCursor Lib "user32.d11" (ByVal bShow As Long) As 
Long 


Platforms: Win 32s, Win 95/98, Win NT 


ShowCursor either shows or hides the mouse cursor. This is not done directly, but rather by 
incrementing or decrementing a counter. Each function call raises or lowers the counter by 1. If the 
counter is negative, the cursor is invisible. It if it non-negative, the cursor is visible. The function returns 
the value of the counter after changing it. 


bShow 
If zero, decrement the counter by 1. If non-zero, increment the counter by 1. 


Example: 


' Hide the mouse cursor for 5 seconds. 
Dim counter As Long ' receives value of cursor visibility counter 


' Hide the cursor by decrementing the counter until it is negative 
Do 


counter = ShowCursor (0) ' decrement by 1 
Loop Until counter < 0 ' keep looping until cursor is hidden 
Sleep 5000 ' pause execution for 5 seconds (5000 milliseconds) 


' Show the cursor by incrementing the counter until it is not negative 
Do 

counter = ShowCursor (1) ' increment by 1 
Loop Until counter => 0 ' keep looping until cursor is visible 


Category: Cursor 


Go back to the alphabetical Function listing. 
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ShowWindow Function 


Declare Function ShowWindow Lib "user32.d1l1l" (ByVal hwnd As Long, ByVal 
nCmdShow As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


Show Window shows (or hides) a window in a certain manner. For example, the function can minimize, maximize, 
or restore a given window. The function returns 0 if the window had been hidden before the call, or a non-zero 
value if it had been visible. 


hwnd 
The handle of the window to change the show status of. 
nCmdShow 

Exactly one of the following flags specifying how to show the window: 
SW_HIDE = 0 

Hide the window. 
SW_MAXIMIZE = 3 

Maximize the window. 
SW_MINIMIZE = 6 

Minimize the window. 
SW_RESTORE = 9 

Restore the window (not maximized nor minimized). 
SW_SHOW =5 

Show the window. 
SW_SHOWMAXIMIZED = 3 

Show the window maximized. 
SW_SHOWMINIMIZED = 2 

Show the window minimized. 
SW_SHOWMINNOACTIVE = 7 

Show the window minimized but do not activate it. 
SW_SHOWNA = 8 

Show the window in its current state but do not activate it. 
SW_SHOWNOACTIVATE = 4 

Show the window in its most recent size and position but do not activate it. 
SW_SHOWNORMAL = 1 

Show the window and activate it (as usual). 





Example: 
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' Maximize the window Forml. Before doing so, make sure 

' that the window is visible. 

Dim retval As Long ' return value 

retval = ShowWindow(Forml.hWnd, SW_SHOW) ' display the window if it's hidden 
retval = ShowWindow(Forml.hWnd, SW_MAXIMIZE) ' maximize the window 





See Also: IsIconic, IsZoomed 
Category: Windows 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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SHQueryRecycleBin Function 





Declare Function SHQueryRecycleBin Lib "shel1l32.d1l1" Alias "SHQueryRecycleBinA" 
(ByVal pszRootPath As String, pSHQueryRBInfo As SHQUERYRBINFO) As Long 








Platforms 


Windows 95: Requires Internet Explorer 4.0 or later with integrated shell installed. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later and Internet Explorer 4.0 or later with integrated shell installed. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


SHQueryRecycleBin retrieves information about how many files (or other items) are currently in the Recycle Bin as well as 
how much disk space they consume. This function will work with the Recycle Bin specific to a certain drive, as well as work 
with the Recycle Bin as considered over the entire system. 


Return Value 


If an error occured, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


pszRootPath 
A path which is on the drive to query the Recycle Bin of. If this string is empty, the function instead queries all 
Recycle Bins on the system as a whole. 

PSHQueryRBInfo 
Receives the number of bytes in the Recycle Bin and the number of items in it. The cbSize member of the structure 
must be initialized before calling the function. 


Example 
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' This code is licensed according to the terms and conditions listed here. 





' Display the number of items in the Recycle Bin on the C: 
' drive and the size of it. 
Dim rbinfo As SHQUERYRBINFO ' information about the bin 


Dim retval As Long ' return value 











' Initialize the size of the structure. 


rboinfo.cbSize = Len(rbinfo) 

" Query the contents of C:'s Recycle Bin. 

retval = SHQueryRecycleBin("C:\", rbinfo) ' the path doesn't have to be the root 
path 


' Display the number of items in the Recycle Bin, if the value is 

' within Visual Basic's numeric display limits. 

If (rboinfo.i64NumItems.LowPart And &H80000000) = &H80000000 Or 
rboinfo.i64NumItems.HighPart > 0 Then 

Debug.Print "Recycle Bin contains more than 2,147,483,647 items." 
Else 
Debug.Print "Recycle Bin contains"; rbinfo.i64NumItems.LowPart; "items." 

End If 

' Likewise display the number of bytes the Recycle Bin is taking up. 

If (rbinfo.i64Size.LowPart And &H80000000) = &H80000000 Or rbinfo.i64Size.HighPart > 
0 Then 

Debug.Print "Recycle Bin consumes more than 2,147,483,647 bytes." 

Else 
Debug.Print "Recycle Bin consumes"; rbinfo.i64Size.LowPart; "bytes." 
End If 












































See Also 


SHEmptyRecycleBin 





Category 
Shell 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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SHUpdateRecycleBinlcon Function 


Declare Function SHUpdateRecycleBinIcon Lib "Shel132.d11" () As Long 





Platforms 


e Windows 95: Requires Internet Explorer 4.0 with integrated shell installed. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 4.0 or later and Internet Explorer 4.0 or later with integrated 
shell installed. 

e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


SHUpdateRecycleBinIcon updates the Recycle Bin icon on the desktop to reflect the state of the systemwide 
Recycle Bin. Since the other Recycle Bin management functions will update this icon on their own, there's 
almost no reason why your applications would need to call this function explicitly. 


Return Value 


If an error occued, the function returns a non-zero error code. If successful, the function returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


" Delete the contents in the system's Recycle Bin, without 





' showing the progress dialog. If an error occurs, be safe and 
' make sure the proper Recyle Bin icon is used. 
Dim retval As Long ' return value 


" Delete the contents of the system's Recycle Bin, if the user OKs it. 
retval = SHEmptyRecycleBin(Forml.hWnd, "", SHERB_ NOPROGRESSUL) 














' If an error occured, be overly save and refresh the Recycle Bin 


' icon. This probably isn't necessary, however. 
If retval <> 0 Then ' error 

retval = SHUpdateRecycleBinIcon () 
End If 





See Also 
SHEmptyRecycleBin 
Category 
Shell 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 
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Sleep Function 


Declare Sub Sleep Lib "kernel32.d1ll1" (ByVal dwMilliseconds As Long) 
Platforms: Win 32s, Win 95/98, Win NT 


Sleep pauses program execution for a certain amount of time. This is more accurate than using a do- 
nothing loop, waiting for a certain amount of time to pass. The function does not return a value. 


dwMilliseconds 
The number of milliseconds to halt program execution for. 


Example: 


' Pause the program for 2 seconds, displaying the system 
" time before and after the pause. 


Debug.Print "The time is "; TimeS ' display the current time 
Sleep 2000 ' 2000 milliseconds = 2 seconds to delay 
Debug.Print "The time is "; TimeS ' this time will be 2 seconds later 


Category: Other 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/sleep.html 
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sndPlaySound Function 


Declare Function sndPlaySound Lib "winmm.d1l" Alias "sndPlaySoundA" (ByVal 
lpszSoundName As String, ByVal uFlags As Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


NOTE: The function sndPlaySound is obsolete. It is superseded by the PlaySound function. 


sndPlaySound plays either a .WAV file or a system-defined sound. If the SVD_NODEFAULT flag is used, the 
function returns 0 if the .WAV file (or system sound) cannot be found and 1 if it is. If the flag is not set, the 
function always returns | and plays the Windows Default sound if the specified sound cannot be found. 


lpszSoundName 
Either the path and filename of the .WAV file to play, or the name of the system sound to play. 
uF lags 
Zero or more of the following flags specifying how to play the sound: 
SND_ALIAS = &H10000 
Play a Windows sound (such as SystemStart, Asterisk, etc.). 
SND_ASYNC = &H1 
Continue program execution immediately after starting to play the sound. 
SND_FILENAME = &H20000 
Play the specified filename. 
SND_LOOP = &H8 
Play the sound repeatedly until sndPlaySound is called again with /JpszSoundName = 
SND_ASYNC must also be set. 
SND_NODEFAULT = &H2 
Do not play the Windows default sound if the specified sound cannot be found. 
SND_NOSTOP = &H10 
Do not stop playing any currently playing sounds. 
SND_NOWAIT = &H2000 
Do not wait if the sound driver is busy. 
SND_SYNC = &HO 
Wait until the sound has finished playing before continuing program execution. 





nn 





Example: 


' Play the Empty Recycle Bin system sound and pause 
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' program execution until the sound is finished playing. 
Dim retval As Long 


retval = sndPlaySound ("EmptyRecycleBin", SND_ALIAS Or SND_SYNC) ' play the 
associated sound 


See Also: PlaySound 
Category: Audio 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/sndplaysound.html 
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socket Function 








Declare Function socket Lib "wsock32.d1ll1" (ByVal af As Long, ByVal prototype As Long, 
ByVal protocol As Long) As Long 





Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


socket creates a new socket used for network communications. The socket is assigned a particular communications protocol 
(such as TCP/IP) upon creation. Before using this function, Winsock must be initialized via calling WSAStartup. 


Return Value 


If successful, the function returns a descriptor of the socket that was created. If an error occured, the function returns 
INVALID_SOCKET (use WSAGetLastError to get the error code). 





Visual Basic-Specific Issues 


None. 


Parameters 


af 
The address family of the protocol to use with the socket. For the Internet, this will be AF_INET (for IP). 
prototype 
The type of protocol to use with the socket. This may be one of the following values: 
SOCK_DGRAM 
A datagram-based protocol. For the Internet, this will typically be UDP/IP. 
SOCK_STREAM 
A two-way stream-based protocol. For the Internet, this will typically be TCP/IP. 
protocol 
The protocol to use with the socket. For the Internet, set this to zero. 
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Constant Definitions 








Const INVALID_SOCKET = &HFFFFFFFF 


Example 


Download the main page of this web site (http://www.vbapi.com). This example supports a very crude implementation of 
HyperText Transport Protocol (HTTP), sending a request to the server and receiving the document. The document 
downloaded, with HTTP headers removed, is output to the Debug window. To prevent the program from appearing to lock up 
in the event of a momentary interruption in the transfer, a nonblocking socket is used. To use this example, place a command 
button named cmdDownload on a form window. 


Note the careful use of GoTo in this example. Since there are lots of things that can go wrong, and WSACleanup must be 
called at the end no matter what happens, the GoTo statements skip down to the end if an unrecoverable error occurs. If VB 


had better exception handling, I would use that instead of GoTo. 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.d1l" (ByVal wVersionRequested As 
































Integer, lpWSAData _ 
As WSADATA) As Long 















































Public Declare Function WSACleanup Lib "wsock32.d1l1" () As Long 

Public Const AF_INET = 2 

Public Const SOCK_STREAM = 1 

Public Declare Function gethostbyname Lib "wsock32.dl11" (ByVal name As String) As 
Long 

Public Type hostent 


h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 
Public Declare Function htons Lib "wsock32.dl1l1" 














~ 


ByVal hostshort As Integer) As 








Integer 
Public Declare Function socket Lib "wsock32.dll" (ByVal af As Long, ByVal prototype 
As Long, 




















ByVal protocol As Long) As Long 





http://216.26.168.92/vbapi/ref/s/socket.html (2 of 5) [9/1/2002 5:50:55 PM] 


Windows API Guide: socket Function 


Public Type sockaddr 
sin_family As Integer 
Sin_port As Integer 
Sin_addr As Long 
Sin_zero As String * 8 
End Type 
Public Declare Function connect Lib "wsock32.d1ll1" (ByVal s As Long, name As sockaddr, 








ByVal namelen _ 
As Long) As Long 
Declare Function ioctlisocket Lib "wsock32.dll1" (ByVal s As Long, ByVal cmd As Long, 














argp As Long) As Long 

Public Const FIONBIO = &H80046671] 
Public Declare Function send Lib "wsock32.dll1" (ByVal s As Long, buf As Any, ByVal 
length As Long, _ 

ByVal flags As Long) As Long 

Public Declare Function recv Lib "wsock32.d1l1" (ByVal s As Long, buf As Any, ByVal 














Cl 
































length As Long, _ 
ByVal flags As Long) As Long 
Public Declare Function closesocket Lib "wsock32.d1l1" (ByVal s As Long) As Long 




















Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 





As Any, Source _ 
As Any, ByVal Length As Long) 
Public Const SOCKET _ERROR = -1 




















' Define a useful macro. 
Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 


MAKEWORD = Val ("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 





























2)) 
End Function 








' *** Place the following code inside the form window. *** 
































Private Sub cmdDownload_Click () 
Dim wsockinfo As WSADATA ' info about Winsock 
Dim sock As Long ' the socket descriptor 
Dim pHostinfo As Long ' pointer to info about the host computer 
Dim hostinfo As hostent ' info about the host computer 
Dim pIPAddress As Long ' pointer to host's IP address 
Dim ipAddress As Long " host's IP address 
Dim sockinfo As sockaddr ' settings for the socket 
Dim buffer As String ' buffer for sending and receiving data 
Dim reply As String ' accumulates server's reply 
Dim retval As Long ' generic return value 




















' Begin a Winsock session. 

retval = WSAStartup (MAKEWORD (2, 2), wsockinfo) 

If retval <> 0 Then 

Debug.Print "Unable to initialize Winsock! --"; retval 
Exit Sub 

















End If 
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' Get information about the server to connect to. 
pHostinfo = gethostbyname ("www.vbapi.com") 
If pHostinfo = 0 Then 
Debug.Print "Unable to resolve host!" 
GoTo Cleanup 























End If 
' Copy information about the server into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 

If hostinfo.h_addrtype <> AF_INET Then 

Debug.Print "Couldn't get IP address of www.vbapi.com!" 
GoTo Cleanup 









































End If 
" Get the server's IP address out of the structure. 
CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 























CopyMemory ipAddress, ByVal plIPAddress, 4 


' Create a socket. 

sock = socket (AF_INET, SOCK_STREAM, 0) 

If sock = SOCKET _ERROR Then 

Debug.Print "Unable to create socket!" 
GoTo Cleanup 





























End If 











' Make a connection to www.vbapi.com:80 (where the web server listens). 
With sockinfo 

' Use Internet Protocol (IP) 

.-Sin_family = AF_INET 























" Connect to port 80. 
-Sin_port = htons (80) 
' Connect to this IP address. 








.-Sin_addr = ipAddress 
' Padding characters. 
Sin_zero = String(8, vbNullChar) 








End With 








Debug.Print "Attempting to connect...." 
retval = connect (sock, sockinfo, Len(sockinfo) ) 








If retval <> 0 Then 
Debug.Print "Unable to connect!" 
GoTo Cleanup 








End If 











' Send an HTTP/GET request for the /index.html file. 
buffer = "GET / HTTP/1.1" & vbCrLf & _ 

"Host: www.vbapi.com" & vbCrLf & _ 

"User-Agent: HTTP-Test-Program" & vbCrLf & vbCrLf 
retval = send(sock, ByVal buffer, Len(buffer), 0) 





























Debug.Print "Sent request. Waiting for reply..." 





' Make the socket non-blocking, so calls to recv don't halt the program 
waiting for input. 
retval = ioctlsocket (sock, FIONBIO, 1) 
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' Read the response from the other system. A more sophisticated program 
' would watch to see if the connection ever times out (i.e., if the 
connection is 
' lost). For brevity, such code is omitted here. 
Do 








buffer = Space (4096) 

retval = recv(sock, ByVal buffer, Len(buffer), 0) 

If retval <> 0 And retval <> SOCKET _ERROR Then 
reply = reply & Left (buffer, retval) 























End If 

" Process background events so the program doesn't appear to freeze. 
DoEvents 

Loop Until retval = 0 








' Print the response from the server. 
Debug.Print "Document Retrieved:" 
Debug.Print reply 














' Perform the necessary cleanup at the end. 








Cleanup: 
retval = closesocket (sock) 
retval = WSACleanup () 

End Sub 


See Also 


closesocket 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/s/socket.html 
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StartDoc Function 








Declare Function StartDoc Lib "gdi32.dll1" Alias "StartDocA" (ByVal hdc As Long, lpdi 
As DOCINFO) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


StartDoc initiates a job for a printer. The function prepares the print spooler to receive information about the document to 
print. The StartDoc and EndDoc functions must bracket all the code which draws the document on the printer (see the 


example for an illustration). 


Return Value 


If an error occured, the function returns either a zero or negative value (Windows NT, 2000: use GetLastError to get the error 
code). If successful, the function returns the print job identifer of the document to print. 


Visual Basic-Specific Issues 


None. 


Parameters 


hdc 
A handle to a device context to the printer to print the document on. 


lpdi 
Briefly describes the document to print. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' 


3 





Print out a page with an ellipse drawn 


pe 


The following are special 


ma 


Declare Function lsi 


Ne on aces 


n 








g, ByVal 


Declare Function lstrcpy Lib 


Strin lpString2 As Long) 


The page is printed on the 





ipulation functions to use pointers 


with a thickened black 

















istrien Lib 


As Long 


' 


ÈÌ 


i 
I 
i 
i 


I 
i 
i 








ĵi 


Variable declarations 


i 
a 
in 
ii 
i 
i 
i 
i 








m 


hPrintDC As Long 
di As DOCINFO '! 
hPen As Long ' 

hOldPen As Long ' 








buffer(0 To 3076 / 4) 








pi2 As PRINTER INFO 2 ' 




















computer's default printer. 
declarations needed to allow string 
to strings. 
"kernel32.d11" Alias "lIstrcpyA" (ByVal lpStringl As 
As Long 
"kernel32.d1l1" Alias "l1strlenA" (ByVal lpString As Long) 











handle to the printer's device context 


information about the document to print 
handle to the pen to draw the ellipse with 


handle to the printer's previously selected pen 





As Long ' 
receives 








printret As Long 


spaceneeded As Long 


retval As Long ' 





re 


Ge 








the devic 





de 
En 








scription of 
umPrinters page. 








tval 








r 


receives th 





' receives space requires for 


eturn value 





and driver names of the 
the semi-conf 


using code 








EnumPrinters (PRINT 





ER 








_ENUM_ 











printret) 


If retval 





pi2.pPrinterName 


De 
En 





ot 


O Then 








bug.Print 
d T 


End If 
Copy the device and driver names 
her information retrieved is not 





EFAULT, 


3076-byte buffer 
info about the default printer 








number of printers returned from 





EnumPrinters 











EnumPrinters 





default printer. 
below, 








bu 


wee 
r 


2, 


"No default printer is configured." 
abort the program 





CO 











re 


pi2.pDriverName 


rG 


hPrintDC 


hPen = CreatePen(PS_SOLID, 

















CE 


Cr 


tval = lstrcpy (pi2.pD 





eate a 








eate a 
































buffer ( 
Space (lstrien (buffer (4) 
riverName, buffer ( 


device context to the printer, 
Crearepe (Tr; 
solid black brush with a thickness of 
0) ) 





pi2.pPrinterName, 





5, RGB(O, 0, 



































the structure. 
needed and is omitted here. 


Space (lstrlen(buffer(l1))) 
tval = lstrcpy (pi2.pPrinterName, 


1)) 
)) 
4)) 


ffer (0), 


For a more detailed 


consult the 


3076, spaceneeded, 


All the 








using its default initialization. 





0, 
5. 





ByVal CLng(0)) 





ile doesn't apply 


Load information about the document 

.cbSize = Len(di) ' size of structure 
lpszDocName = "Printer API Demonstration" '! 
lpszOutput = 0 ' do not print to a file 
lpszDatatype = ™"" ' data type of f 

.fwType = 0 ' no additional information 

Begin the print job. 

tval = StartDoc(hPrintDC, di) 

Begin the first and only page to print. 
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name of document 
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retval = StartPage (hPrintDC) 

' Select the pen for use with the printer. 

hOldPen = SelectObject (hPrintDC, hPen) 

' Draw an ellipse with bounding rectangle corners (1000,1500)-(2000, 3000) 
retval = Ellipse(hPrintDC, 1000, 1500, 2000, 3000) 
' Restore the printer's previously selected pen. 
retval = SelectObject (hPrintDC, hOldPen) 

' End information about the first and only page. 
retval = EndPage(hPrintDC) 









































' End information about the document. 
retval = EndDoc(hPrintDC) 























' The printer will now begin printing the document. 














' Delete the pen created for drawing. 
retval = DeleteObject (hPen) 

















' Delete the device context to the printer. 
retval = DeleteDC (hPrintDC) 























See Also 


EndDoc 


Category 


Printers 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








Last Modified: November 1, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/startdoc.html 
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StartPage Function 











Declare Function StartPage Lib "gdi32.d1l1" (ByVal hDC As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 2.0 or later. 


Description & Usage 


StartPage informs the print spooler that the program is about to begin drawing the contents of a printed page. The StartPage 
and EndPage functions must bracket all code which draws the contents of the printed page. The print spooler must have 
already been informed that it is receiving a document to be printed via StartDoc. Windows 95/98: This function automatically 
resets the printer configuration to its settings when the device context to the printer was first obtained. Any alterations to the 
prior settings must be made after each time StartPage is called. 


Return Value 


If an error occured, the function returns either zero or a negative value (Windows NT, 2000: use GetLastError to get the error 
code). If successful, the function returns a positive value. 


Visual Basic-Specific Issues 


None. 


Parameters 


hDC 
A handle to a device context to the printer being used to print the document. 


Example 


E 


This code is licensed according to the terms and conditions listed here. 


' 


Print out a page with an ellipse drawn with a thickened black 
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' pen on it. The page is printed on the computer's default printer. 





m 





' The following are specia 


























declarations needed to allow string 



































' manipulation functions to use pointers to strings. 

Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl As 
String, ByVal lpString2 As Long) As Long 

Declare Function lstrlen Lib "kernel32.d11" Alias "lIstrlenA" (ByVal lpString As Long) 
As Long 

' Variable declarations 

Dim hPrintDC As Long ' handle to the printer's device context 

Dim di As DOCINFO ' information about the document to print 

Dim hPen As Long ' handle to the pen to draw the ellipse with 

Dim hOldPen As Long ' handle to the printer's previously selected pen 

Dim buffer(0 To 3076 / 4) As Long ' 3076-byte buffer 








im pi2 As PRINTER INFO 2 : 


















































receives info about the default printer 






























































Dim printret As Long ' receives the number of printers returned from EnumPrinters 
Dim spaceneeded As Long ' receives space requires for EnumPrinters 
Dim retval As Long ' return value 
' Get the device and driver names of the default printer. For a more detailed 
' description of the semi-confusing code below, consult the 
' EnumPrinters page. 
retval = EnumPrinters (PRINTER_ENUM_DEFAULT, "", 2, buffer(0), 3076, spaceneeded, 
printret) 
If retval = 0 Then 
Debug.Print "No default printer is configured." 














End ' abort the program 
End If 





' Copy the device and driver names to the structure. 








All the 


' other information retrieved is not needed and is omitted here. 
pi2.pPrinterName = Space (lstrilen (buffer (1) ) 








retval = lstrcpy(pi2.pPrinterName, buffer ( 











pi2.pDriverName = Space (lstrlen (buffer (4) 














' Create a device context to the printer, 








) 
retval = lstrcpy(pi2.pDriverName, buffer (4 





1 
) 
) 





hPrintDC = CreateDC("", pi2.pPrinterName, 0 





hPen = CreatePen(PS_ SOLID, 5, 














RGB (0, 0, 0)) 






































) 
)) 


) 








using its det 


Fault initialization. 





, ByVal CLng(0) ) 
" Create a solid black brush with a thickness of 5. 








' Load information about the document to print into the structure. 
di.cbSize = Len(di) ' size of structure 

di.lpszDocName = "Printer API Demonstration" ' name of document 
di.lpszOutput = 0 ' do not print to a file 

di.lpszDatatype = "" ' data type of file doesn't apply 

di.fwType = 0 ' no additional information 





' Begin the print job. 


retval = StartDoc(hPrintDC, di) 
' Begin the first and only page to print. 

















retval = StartPage (hPrintDC) 
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' Select the pen for use with the printer. 

hoOldPen = SelectObject (hPrintDC, hPen) 

' Draw an ellipse with bounding rectangle corners (1000,1500)-(2000, 3000) 
retval = Ellipse(hPrintDC, 1000, 1500, 2000, 3000) 

' Restore the printer's previously selected pen. 





















































retval = SelectObject (hPrintDC, hOldPen) 

' End information about the first and only page. 
retval = EndPage(hPrintDC) 

' End information about the document. 

retval = EndDoc(hPrintDC) 














' The printer will now begin printing the document. 





' Delete the pen created for drawing. 
retval = DeleteObject (hPen) 




















' Delete the device context to the printer. 
retval = DeleteDC (hPrintDC) 























See Also 


EndPage 


Category 


Printers 


Go back to the alphabetical Function listing. 





Go back to the Reference section index. 





Last Modified: November 5, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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StretchBlit Function 


Declare Function StretchBlt Lib "gdi32.d1l1" (ByVal hdc As Long, ByVal x As 
Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hSrcDC As Long, ByVal xSrc As Long, ByVal ySrc As Long, ByVal hSrcWidth As 
Long, ByVal nSrcHeight As Long, ByVal dwRop As Long) As Long 


StretchBlt copies a section of an image from one device to another. This function also allows you to change the 
original size and dimensions of the image section, unlike the related function BitBlt. In addition to using the straight 





"copy" method, you can specify other ways of copying the image with the dwRop parameter. What the function 
actually does is perform a binary operation on the color of the source and destination pixel to calculate the color of the 
pixel in the transfered image. The point you specify as the location of the copied image in the target object will be the 
upper-left corner of the image portion. The function returns 0 if the function failed and 1 if it succeeded. 


hDestDC 
The device context of the target object (the one that receives the image piece). 


The x coordinate of the point to put the image inside the target. 
y 
The y coordinate of the point to put the image inside the target. 
nWidth 
The width of the image piece in the target. 
nHeight 
The height of the image piece in the target. 
xSrc 
The x coordinate of the upper-left corner of the image piece in the source. 
ySre 
The y coordinate of the upper-left corner of the image piece in the source. 
nSrc Width 
The width of the image piece in the source. 
nSrcHeight 
The height of the image piece in the source. 
dwRop 
Exactly one of the following flags specifying what method to use to copy the source image: 
SRCAND = &H8800C6 
Logically And the two color values (destination = source And destination). 
SRCCOPY = &HCC0020 
Copy the source image exactly (destination = source). 
SRCERASE = &H440328 
Logically And the source image and the destination's binary inverse (destination = source And (Not 
destination). 
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SRCINVERT = &H660046 

Logically Xor the two color values (destination = source Xor destination). 
SRCPAINT = &HEE0086 

Logically Or the two color values (destination = source Or destination). 


Example: 


' Copy a portion of the image in PictureBoxl to PictureBox2 and 

' stretch it to triple its original width. The image's original dimensions are 
' 16x32; its new ones are 48x32. 

' Source image coordinates: (45,50)-(60, 81) 

' Target image coordinates: (0,0)-(47,31) 


Dim retval As Long ' function return value 


retval = BitBlt (PictureBox2.hdc, 0, 0, 48, 32, PictureBoxl.hdc, 45, 50, 16, 32, 
SRCCOPY) 


See Also: BitBlt 
Category: Bitmaps 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/stretchblt.html 
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SubtractRect Function 








Declare Function SubtractRect Lib "user32.d11" (lprcDst As RECT, lprcSrcl As RECT, 
lprcSrce2 As RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


SubtractRect subtracts a smaller rectangle from a larger one. Rectangle subtraction is defined as follows. The large and 
small rectangles must intersect completely along one entire side, neither extanding farther along that side than the other. In 
other words, they must share a common side. If this is true, then all of the large rectangle that is not also part of the small 
rectangle is also a rectangle. This rectangle is the subtraction rectangle. This rectangle is put into the variable passed as 
IprcDst. If the two rectangles fail to meet the criteria, JprcDst is set equal to the large rectangle and the function returns 0. 
If subtraction is possible, the function returns 1. 


IprcDst 

Variable that receives the subtraction rectangle. 
lprcSrcl 

The large rectangle; that is, the rectangle subtracted from. 
lprcSrc2 

The small rectange; that is, the rectangle subtracted. 





Example: 
' A demonstration of rectangle subtract. target = big - small. 
' big = (20,30)-(70,80). small = (20,30)-(40,80). Note that the left side of the 


two rectangles is 
" common. target will be set to (41,30)-(70,80). 
Dim target As RECT, big As RECT, small As RECT 

















Dim retval As Long ' return value 

' Set the big and small rectangles 

retval = SetRect (big, 20, 30, 70, 80) ' big = (20,30)-(70,80) 
retval = SetRect(small, 20, 30, 40, 80) ' small = (20,30)-(40, 80) 





' Subtract small from big and put the result into target 
retval = SubtractRect (target, big, small) ' now target = (41,30)-(70, 80) 


See Also: IntersectRect, UnionRect 
Category: Rectangles 





Go back to the alphabetical Function listing. 





Go back to the Reference section index. 
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SwapMouseButton Function 








Declare Function SwapMouseButton Lib "user32.d11" (ByVal bSwap As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


SwapMouseButton alters the mapping used for the mouse buttons. Windows allows you to interpret left-button clicks as 
right-button clicks and vice versa. This functionality is designed for people who use the mouse left-handed. Of course, 
Windows is normally the only program to ever change this, so do it with caution -- it of course affects mouse usage in all 
programs as well as Windows itself. The function returns 1 if successful, or 0 if an error occured. 


bSwap 
Determines the mouse button mapping. 0 means do not swap the buttons (left means left, right means right). 1 means 
swap the left and right buttons (left means right, right means left). Note that "swapping" is relative to the normal left- 
left mapping, not to the current one. 


Example: 


' Swap the left and right mouse buttons. You probably would never 

' do this in a program unless the user specifically asked for it (as he/she does in 
' Windows's Control Panel). 

Dim retval As Long ' return value 








retval = SwapMouseButton (1) ' switch the left and right buttons 
" Now left means right even if this had previously been the cas 
Debug.Print "The mouse buttons are currently swapped." 














Category: Mouse 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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SystemParametersinfo Function 
Declare Function SystemParametersInfo Lib "user32.dl1" Alias 
"SystemParametersInfoA" (ByVal uAction As Long, ByVal uiParam As Long, pvParam As 

















Any, ByVal fWinIni As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


SystemParametersInfo reads or sets information about numerous settings in Windows. These include Windows's 
accessibility features as well as various settings for other things. The exact behavior of the function depends on the flag 
passed as wAction. All sizes and dimensions used by this function are measured in pixels. Whenever using a structure to 
receive information, the member identifying the size of the structure (if one exists) must be correctly set beforehand. Note 
that, when setting properties via this function, that the user may not expect such settings to be changed; normally only the 
Control Panel applets set many of these properties. The return value in almost all cases (there are exceptions, which are 
noted) is 0 if the function failed, or a non-zero value if the function succeeded. Note to Visual Basic users: Whenever 
passing a string as pvParam, must explictly add the ByVal keyword before it. This must also be done when explicitly 
setting the pvParam parameter to 0. See the examples for a demonstration of when and how this is done. 


uAction 

Exactly one of the following flags specifying the action taken by the function: 

SPI_GETACCESSTIMEOUT = 60 
Retrieve information about the time-out period associated with the accessibility features. uiParam must be the 
size of the ACCESSTIMEOUT structure. pvParam is an ACCESSTIMEOUT structure receiving the time-out 
settings. 

SPI_GETANIMATION = 72 
Win 95/98 only: Retrieve information about the animation effects associated with the user's actions. uiParam 
must be 0. pvParam is an ANIMATIONINFO structure receiving the animation effects settings. 

SPI_GETBEEP = 1 
Determine if the warning beeper is on or off. uiParam must be 0. pvParam is a Long-type variable which 
receives 0 if the warning beeper is off, or a non-zero value if it is on. 

SPI_GETBORDER = 5 
Retrieve the window sizing border multiplier factor, which determines the width of a window's sizing border. 
uiParam must be 0. pvParam is a Long-type variable which receives the current setting. 

SPI_GETDEFAULTINPUTLANG = 89 
Win 95/98 only: Retrieve a handle to the keyboard layout used for the system's default input language. 
uiParam must be 0. pvParam is a Long-type variable which receives the handle. 

SPI_GETDRAGFULLWINDOWS = 38 
Win 95/98 only: Determine if Windows displays the entire contents of a window when it is moved or resized 
(instead of merely displaying an outline of it). uiParam must be 0. pvParam is a Long-type variable which 
receives 0 if the contents are not displayed, or a non-zero value if they are. 

SPI_GETFASTTASKSWITCH = 35 
Determine if fast Alt-Tab task switching is enabled. uiParam must be 0. pvParam is a Long-type variable 
which receives 0 if fast task switching is not enabled, or a non-zero value if it is. 
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SPI_GETFILTERKEYS = 50 
Retrieve the settings of the FilterKeys accessibility feature. uiParam must be the size of the FILTERKEYS 
structure. pvParam is a FILTERKEYS structure which receives the current settings of FilterKeys. 
SPI_GETFONTSMOOTHING = 74 
Determine whether font smoothing is enabled or not. uiParam must be 0. pvParam is a Long-type variable 
which receives 0 if font smoothing is not enabled, or a non-zero value if it is. 
SPI_GETGRIDGRANULARITY = 18 
Retrieve the current granularity of the desktop sizing grid. uiParam must be 0. pvParam is a Long-type 
variable which receives the current setting. 
SPI_GETHIGHCONTRAST = 66 
Win 95/98 only: Retrieve the settings of the HighContrast accessibility feature. uiParam must be 0. pyParam 
is a HIGHCONTRAST structure which receives the current settings of HighContrast. 
SPI_GETICONMETRICS = 45 
Win 95/98 only: Retrieve the metrics associated with icons, which determine how Windows displays icons. 
uiParam must be 0. pvParam is an ICONMETRICS structure which receives the icon metrics. 
SPIGETICONTITLELOGFONT = 31 
Retrieve information about the logical font used to display the titles of icons. uiParam must be the size of the 
LOGFONT structure. pvParam is a LOGFONT structure which receives information about the logical font. 
SPIGETICONTITLEWRAP = 25 
Determine if Windows word-wraps the text of icon titles. uiParam must be 0. pvParam is a Long-type 
variable which receives 0 if word-wrapping is not enabled, or a non-zero value if it is. 
SPIGETKEYBOARDDELAY = 22 
Retrieve the current keyboard repeat delay setting, which is the time before a held key begins to repeat. 
uiParam must be 0. pvParam is a Long-type variable which receives the current delay setting (a value 
between 0 and 3). 
SPI_GETKEYBOARDPREF = 68 
Win 95/98 only: Determine if the user relies on the keyboard instead of the mouse and wants programs to 
display keyboard interfaces which are otherwise hidden. uiParam must be 0. pvParam is a Long-type variable 
which receives 0 if the user does not rely on the keyboard, or a non-zero value if the user does. 
SPI_GETKEYBOARDSPEED = 10 
Retrieve the current keyboard repeat speed setting, which is the speed between repeats when a key is held. 
uiParam must be 0. pvParam is a Long-type variable which receives the current speed setting (a value 
between 0 and 31). 
SPIGETLOWPOWERACTIVE = 83 
Win 95/98 only: Determine if the system enters a low-power mode after a period of inactivity. uiParam must 
be 0. pvParam is a Long-type variable which receives 0 if low-power mode is not enabled, or a non-zero 
value if it is. 
SPI_GETLOWPOWERTIMEOUT = 79 
Win 95/98 only: Retrieve the time, in seconds, which must elapse before Windows enters low-power mode. 
uiParam must be 0. pvParam is a Long-type variable which receives the current timeout value. 
SPI_GETMENUDROPALIGNMENT = 27 
Determine if popup menus are left- or right-aligned. uiParam must be 0. pvParam is a Long-type variable 
which receives 0 if the menus are right-aligned, or a non-zero value if they are left-aligned. 
SPI_GETMINIMIZEDMETRICS = 43 
Win 95/98 only: Retrieve the metrics associated with minimized windows, which specify how Windows 
displays minimized windows. uiParam must be the size of the MINIMIZEDMETRICS structure. pvParam is 
a MINIMIZEDMETRICS structure which receives the minimized window metrics. 
SPI_GETMOUSE = 3 
Retrieve the x-axis and y-axis threshold values for the mouse as well as the mouse speed. uiParam must be 0. 
pvParam is a 3-element array of Long-type variables which receives the x-threshold, y-threshold, and mouse 
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speed. 

SPI_GETMOUSEKEYS = 54 
Retrieve the settings of the MouseKeys accessibility feature. uiParam must be the size of the MOUSEKEYS 
structure. pvParam is a MOUSEKEYS structure which receives the current settings of MouseKeys. 

SPI_GETMOUSETRAILS = 94 
Win 95/98 only: Retrieve the current mouse trails setting. uiParam must be 0. pvParam receives 0 or | if 
mouse trails are not enabled, or a value greater than one identifying the number of cursor images making up 
the mouse trail. 

SPI_GETNONCLIENTMETRICS = 41 
Win 95/98 only: Retrieve the metrics associated with the nonclient areas of windows, which determine how 
Windows renders nonclient areas. uiParam must be 0. pvParam is a NONCLIENTMETRICS structure which 
receives the nonclient area metrics. 

SPI_GETPOWEROFFACTIVE = 84 
Win 95/98 only: Determine if the system enters a power-off mode after a period of inactivity. uiParam must 
be 0. pvParam is a Long-type variable which receives 0 if power-off mode is not enabled, or a non-zero value 
if power-off mode is enabled. 

SPI_GETPOWEROFFTIMEOUT = 80 
Win 95/98 only: Retrieve the time-out value, in seconds, that must elapse before Windows enters power-off 
mode. uiParam must be 0. pvParam is a Long-type variable which receives the time-out value for power-off 
mode. 

SPI_GETSCREENREADER = 70 
Win 95/98 only: Determine if a screen reader utility is running. If it is, applications should present more 
textual output instead of graphical output to help the reader function better. uiParam must be 0. pvParam is a 
Long-type variable which receives 0 if no screen reader is running, or a non-zero value if one is. 

SPI_GETSCREENSAVEACTIVE = 16 
Determine if a screen saver is set to run. uiParam must be 0. pvParam is a Long-type variable which receives 
0 if no screen saver is set to run, or a non-zero value if one is. 

SPI_GETSCREENSAVETIMEOUT = 14 
Retrieve the time-out period, in seconds, which must elapse before the screen saver begins running. uiParam 
must be 0. pvParam is a Long-type variable which receives the time-out value. 

SPI_LGETSERIALKEYS = 62 
Win 95/98 only: Retrieve the settings of the SerialKeys accessibility feature. uiParam must be 0. pvParam is 
a SERIALKEYS structure which receives the current settings of SerialKeys. 

SPI_GETSHOWSOUNDS = 56 
Determine if the user desires visual information to replace or suppliment otherwise audio-only output. 
uiParam must be 0. pvParam is a Long-type variable which receives 0 if programs should not display this 
added visual information, or a non-zero value if they should. 

SPI_GETSOUNDSENTRY = 64 
Retrieve the settings of the SoundSentry accessibility feature. uiParam must be the size of the 
SOUNDSENTRY structure. pvParam is aSOUNDSENTRY structure which receives the current settings of 
SoundSentry. 

SPIGETSTICKYKEYS = 58 
Retrieve the settings of the StickyKeys accessibility feature. uiParam must be the size of the STICK YKEYS 
structure. pvParam is a STICKYKEYS structure which receives the settings of StickyKeys. 

SPI_GETTOGGLEKEYS = 52 
Retrieve the settings of the ToggleKeys accessibility feature. uiParam must be the size of the 
TOGGLEKEYS structure. pvParam is a TOGGLEKEYS structure which receives the current settings of 
ToggleKeys. 

SPIGETWINDOWSEXTENSION = 92 
Win 95/98 only: Determine if the Windows extensions are installed. Win 95 requires that Microsoft Plus! be 
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installed to get the extensions; the extensions are integrated as a part of Win 98. uiParam must be 1. pvParam 
must be 0. The function returns 0 if the extensions are disabled, or a non-zero value if they are enabled. 
SPI_GETWORKAREA = 48 
Win 95/98 only: Retrieve the size of the working area, which is a rectangle identifying the area of the 
desktop not obscured by the taskbar. uiParam must be 0. pvParam is a RECT structure which receives the 
rectangle of the working area. 
SPIICONHORIZONTALSPACING = 13 
Set the width of the icon spacing cell. uiParam is the new setting for the width. pvParam must be 0. 
SPIICONVERTICALSPACING = 24 
Set the height of the icon spacing cell. uiParam is the new setting for the height. pyParam must be 0. 
SPI_LLANGDRIVER = 12 
Win 95/98 only: Retrieve the filename of the language driver. uiParam must be 0. pvParam is a String (with 
sufficient buffer space) which receives the filename of the language driver. 
SPI_SETACCESSTIMEOUT = 61 
Set information associated with the time-out period associated with the accessibility features. uiParam must 
be the size of the ACCESSTIMEOUT structure. pvParam is an ACCESSTIMEOUT structure holding the 
new time-out period settings. 
SPI_SETANIMATION = 73 
Win 95/98 only: Set information about the animation effects associated with the user's actions. uiParam must 
be 0. pvParam is an ANIMATIONINFO structure holding the new animation effects settings. 
SPI_SETBEEP = 2 
Turn the warning beeper on or off. uiParam is 0 to turn the beeper off, or a non-zero value to turn it on. 
pvParam must be 0. 
SPI_SETBORDER = 6 
Set the window sizing border multiplier factor, which determines the width of a window's sizing border. 
uiParam is the new setting. pyParam must be 0. 
SPI_SETCURSORS = 87 
Reload the images used for the system cursors. uiParam and pvParam must be 0. 
SPI_SETDEFAULTINPUTLANG = 90 
Win 95/98 only: Set the keyboard layout used for the system's default input language. uiParam is a handle to 
the keyboard layout to use. pvParam must be 0. 
SPI_SETDESKPATTERN = 21 
Set the current desktop pattern bitmap by causing Windows to reread the Pattern setting in the [Desktop] 
section of WIN.INI. Both uiParam and pvParam must be 0. 
SPI_SETDESKWALLPAPER = 20 
Set the current desktop wallpaper bitmap. uiParam must be 0. pvParam is a String holding the filename of 
the bitmap file to use as the wallpaper. 
SPI_SETDOUBLECLICKTIME = 32 
Set the time, in milliseconds, within which two successive mouse clicks must occur for Windows to interpret 
the input to be a double click. uiParam is the new double click time. pvParam must be 0. 
SPI_SETDOUBLECLKHEIGHT = 30 
Set the height of the rectangle within which two successive mouse clicks must occur for Windows to interpret 
the input to be a double click. uiParam is the new height. pvParam must be 0. 
SPI_SETDOUBLECLKWIDTH = 29 
Set the width of the rectangle within which two successive mouse clicks must occur for Windows to interpret 
the input to be a double click. uiParam is the new width. pvParam must be 0. 
SPI_SETDRAGFULLWINDOWS = 37 
Win 95/98 only: Turn dragging of full windows (displaying the contents of a window while moving or 
resizing instead of just an empty border) on or off. uiParam is 0 to turn dragging of full windows off, or a non- 
zero value to turn it on. 











http://216.26.168.92/vbapi/ref/s/systemparametersinfo.html (4 of 8) [9/1/2002 5:52:01 PM] 


Windows API Guide: SystemParametersInfo Function 


SPI_SETDRAGHEIGHT = 77 
Win 95/98 only: Set the height of the rectangle which the cursor must move out of with a button depressed 
for Windows to begin a drag operation. uiParam is the new height. pvParam must be 0. 
SPI_SETDRAGWIDTH = 76 
Win 95/98 only: Set the width of the rectangle which the cursor must move out of with a button depressed 
for Windows to begin a drag operation. uiParam is the new width. pvParam must be 0. 
SPISETFASTTASKS WITCH = 36 
Turn fast Alt-Tab task switching on or off. uiParam is 0 to turn fast switching off, or a non-zero value to turn 
it on. pyParam must be 0. 
SPI_SETFILTERKEYS = 51 
Set the settings of the FilterKeys accessibility feature. uiParam must be the size of the FILTERKEYS 
structure. pvParam is a FILTERKEYS structure holding the new settings for FilterKeys. 
SPI_SETFONTSMOOTHING = 75 
Turn font smoothing on or off. uiParam is 0 to turn font smoothing off, or a non-zero value to turn it on. 
SPI_SETGRIDGRANULARITY = 19 
Set the granularity of the desktop sizing grid. uiParam is the new setting. pvParam must be 0. 
SPI_SETHIGHCONTRAST = 67 
Win 95/98 only: Set the settings of the HighContrast accessibility feature. uiParam must be 0. pvParam is a 
HIGHCONTRAST structure holding the new settings for HighContrast. 
SPISETICONMETRICS = 46 
Win 95/98 only: Set the metrics associated with icons, which specify how Windows displays icons. uiParam 
must be 0. pvParam is an ICONMETRICS structure holding the new icon metrics. 
SPI_SETICONS = 88 
Reload the images used for the system icons. uiParam and pvParam must be 0. 
SPI_SETICONTITLELOGFONT = 34 
Set the logical font used to display the text of icon titles. uiParam must be the size of the LOGFONT 
structure. pvParam is a LOGFONT structure holding the logical font to use. 
SPI_SETICONTITLEWRAP = 26 
Turn the word-wrapping of icon titles on or off. uiParam is 0 to turn word-wrapping off, or a non-zero value 
to turn it on. pvParam must be 0. 
SPISETKEYBOARDDELAY = 23 
Set the keyboard repeat-delay setting, which is the time that must elapse before a held key begins to repeat. 
uiParam is the new delay setting, between 0 and 3 inclusive. pvParam must be 0. 
SPI_SETKEYBOARDPREF = 69 
Win 95/98 only: Tell Windows whether the user depends on the keyboard as the main input device and 
wishes programs to display additional keyboard-based interfaces. uiParam is 0 to not indicate a keyboard 
preference, or a non-zero value to indicate one. pvParam must be 0. 
SPI_SETKEYBOARDSPEED = 11 
Set the keyboard repeat-speed setting, which specifies the rate at which keys are repeated. uiParam is the new 
speed setting, between 0 and 31 inclusive. pvParam must be 0. 
SPI_SETLANGTOGGLE = 91 
Win 95/98 only: Set the hot key used to switch keyboard input languages. The new value is read from the 
registry at HKREY_CURRENT_USER\keyboard layout\toggle: 1 sets the hot key to ALT+SHIFT, 2 sets the 
hot key to CTRL+SHIFT, and 3 disables the hot key. uiParam and pvParam must be 0. 
SPISETLOWPOWERACTIVE = 85 
Win 95/98 only: Turn the low-power mode after a period of inactivity on or off. uiParam is 0 to deactivate 
low-power mode, or | to activate to. pyParam must be 0. 
SPISETLOWPOWERTIMEOUT = 81 
Win 95/98 only: Set the time-out period (in seconds) which must elapse after user input before Windows 
enters low-power mode. uiParam is the new time-out period. pyParam must be 0. 
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SPISETMENUDROPALIGNMENT = 28 
Set whether pop-up menus open to the left or to the right. uiParam is 0 if they open to the left, or a non-zero 
value if they open to the right. pvParam must be 0. 

SPI_SETMINIMIZEDMETRICS = 44 
Win 95/98 only: Set the metrics associated with minimized windows, which determine how Windows 
displays minimized windows. uiParam must be 0. pvParam is a MINIMIZEDMETRICS structure holding 
the new metrics. 

SPI_SETMOUSE = 4 
Set the x-axis and y-axis threshold values for the mouse as well as the mouse speed. uiParam must be 0. 
pvParam is a three-element Long-type array; the first element is the x-threshold, the second element is the y- 
threshold, and the third element is the mouse speed. 

SPISETMOUSEBUTTONSWAP = 33 
Swap or unswap the meanings of the left and right mouse buttons. uiParam is 0 to restore the left-to-left/right- 
to-right mapping, or a non-zero value to swap the buttons into a left-to-right/right-to-left mapping. pvParam 
must be 0. 

SPI_SETMOUSEKEYS = 55 
Set the settings of the MouseKeys accessibility feature. uiParam must be the size of the MOUSEKEYS 
structure. pvParam is a MOUSEKEYS structure holding the new settings for MouseKeys. 

SPISETMOUSETRAILS = 93 
Win 95/98 only: Set the length of the mouse trail. uiParam is 0 or 1 to turn mouse trails off, or a value 
greater than one identifying the number of cursor images used to make up the mouse trail. pyParam must be 
0. 

SPI_LSETNONCLIENTMETRICS = 42 
Win 95/98 only: Set the metrics associated with the non-client areas of windows, which determine how 
Windows displays the non-client areas. uiParam must be 0. pvParam is a NONCLIENTMETRICS structure 
holding the new metrics. 

SPI_SETPENWINDOWS = 49 
Win 95/98 only: Load or unload Microsoft Pen for Windows, if available. uiParam is 0 to unload Pen, or a 
non-zero value to load Pen. pvParam must be 0. 

SPI_SETPOWEROFFACTIVE = 86 
Win 95/98 only: Set whether the system powers down after a period of inactivity. uiParam is 0 to not enter 
power-off mode, or a non-zero value to enter power-off mode. pvParam must be 0. 

SPI_SETPOWEROFFTIMEOUT = 82 
Win 95/98 only: Set the time-out period, in seconds, which must elapse without user input before Windows 
enters power-off mode. uiParam is the new time-out period. pvParam must be 0. 

SPI_SETSCREENREADER = 71 
Win 95/98 only: Set whether a screen-reading program is currently running. uiParam is 0 if no reader is in 
use, or a non-zero value if one is. pyParam must be 0. 

SPI_SETSCREENSAVEACTIVE = 17 
Set whether Windows activates a screen saver after a period of inactivity. uiParam is 0 to turn the screen 
saver off, or a non-zero value to turn it on. pyParam must be 0. 

SPI_SETSCREENSAVETIMEOUT = 15 
Set the time-out period, in seconds, which must elapse before Windows launches a screen saver. uiParam is 
the new time-out period. pvParam must be 0. 

SPI_SETSERIALKEYS = 63 
Win 95/98 only: Set the settings of the SerialKeys accessibility feature. uiParam must be 0. pvParam is a 
SERIALKEYS structure holding the new settings for SerialKeys. 

SPI_SETSHOWSOUNDS = 57 
Turn the ShowSounds accessibility feature on or off. uiParam is 0 to turn ShowSounds off, or a non-zero 
value to turn ShowSounds on. pvParam must be 0. 
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SPI_LSETSOUNDSENTRY = 65 
Set the settings of the SoundSentry accessibility feature. uiParam must be the size of the SOUNDSENTRY 
structure. pvParam is a SOUNDSENTRY structure holding the new settings for SoundSentry. 

SPI_LSETSTICKYKEYS = 59 
Set the settings of the StickyKeys accessibility feature. uiParam is the size of the STICK YKEYS structure. 
pvParam is a STICKYKEYS structure holding the new settings for StickyKeys. 

SPI_SETTOGGLEKEYS = 53 
Set the settings of the ToggleKeys accessibility feature. uiParam is the size of the TOGGLEKEYS structure. 
pvParam is a TOGGLEKEYS structure holding the new settings for ToggleKeys. 

SPI_LSETWORKAREA = 47 
Win 95/98 only: Set the rectangle defining the working area of the desktop. The working area is the area of 
the desktop not obscured by the taskbar. uiParam must be 0. pvParam is a RECT structure holding the new 
working area rectangle. 








uiParam 
The purpose of this parameter varies with wAction. 
pvParam 
The purpose of this parameter varies with uAction. In VB, if this is to be set as a string or to 0, the ByVal keyword 
must preceed it. 
fWinlni 
Zero or more of the following flags specifying the change notification to take place. Generally, this can be set to 0 if 
the function merely queries information, but should be set to something if the function sets information. 
SPIF_SENDWININICHANGE = &H2 
Broadcast the change made by the function to all running programs. 
SPIF_UPDATEINIFILE = &H1 
Save the change made by the function to the user profile. 


Example #1: 


Set the desktop wallpaper to the Clouds.bmp that comes with Windows. 
Note how the string passed to the function is preceeded by the ByVal keyword. 











Dim windir As String ' receives the path of the Windows directory 
Dim cloudpath As String ' filename of Clouds.bmp 
Dim retval As Long ' return value 


' Get the path of the Windows directory. 























windir = Space (255) ' make room in the buffer 

retval = GetWindowsDirectory(windir, 255) ' get the path name 

windir = Left (windir, InStr(windir, vbNullChar) =- 1) " trim the null character and 
unused characters 

cloudpath = windir & "Clouds.bmp" ' add the filename to the path 


Set the Windows wallpaper, saving the change and notifying all programs 
retval = SystemParametersInfo(SPI_SETDESKWALLPAPER, 0, ByVal cloudpath, 
SPIF_SENDWININICHANGE Or SPIF_UPDATEINIFILE) 



























































Example #2: 





Tell the user whether the MouseKeys accessibility feature is on 
' or off. Note how the structure's cbhSize parameter must be set first. 
Dim mk As MOUSEKEYS ' holds settings for MouseKeys 
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Dim retval As Long ' return value 


mk.cbSize = Len (mk) " set the size of the structure 

' Load the MouseKeys settings into the structure. 

retval = SystemParametersInfo(SPI_GETMOUSEKEYS, Len(mk), mk, 
notify 

' Display whether MouseKeys is on or off. 

If (mk.dwFlags And MKF_MOUSEKEYSON) = MKF_MOUSEKEYSON Then 
Debug.Print "MouseKeys is on." 

Else 

Debug.Print "MouseKeys is off." 

End If 




















See Also: GetSystemMetrics 
Category: Accessibility 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/systemparametersinfo.html 
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SystemTimeToFileTime Function 








Declare Function SystemTimeToFileTime Lib "kernel32.dll1" (lpSystemTime As SYSTEMTIME, 
lpFileTime As FILETIME) As Long 
































Platforms: Win 32s, Win 95/98, Win NT 


SystemTimeToFileTime converts a time and date stored in a SYSTEMTIME structure to an identical time and date stored in a 
FILETIME structure. The former structure provides a easier way to access a date and time, whereas the latter is used by 
Windows to identify times and dates associated with files. The data put into the FILETIME structure identifies the same time 
and date as the source structure does. The function returns 0 if an error occured, or 1 if successful. 





lpSystemTime 

The date and time, in SYSTEMTIME format, to convert. 
lpFileTime 

Receives the date and time converted to FILETIME format. 


Example: 




















' Determine if file C:\MyProgram\datafile.txt was created before 
' Jan 5, 1999. Note how CreateFile's alternate declare must be used under Win 95/98 - 

















' see that function's page for more information. 







































































































































































Dim hfile As Long ' receives the handle to the file 

Dim ctime As FILETIME ' receives creation date and time of the file 

Dim atime As FILETIME ' receives last access date and time of the file 

Dim wtime As FILETIME ' receives last write-to date and time of the file 

Dim jantime As SYSTEMTIME ' will be set to Jan 5, 1999 

Dim janfiletime As FILETIME ' will receive analogous time as jantime 

Dim comptimes As Long ' receives comparison of ctime and janfiletime 

Dim retval As Long ' return value 

" Get a handle to the file (note how the alternate declare is used): 

hfile = CreateFileNS ("C:\MyProgram\datafile.txt", GENERIC_READ, FILE_SHARE_ READ, 0, 






































































































































OPEN_EXISTING, FILE ATTRIBUTE ARCHIVE, 0) 

If hfile = -1 Then ' if the file could not be opened 
Debug.Print "Could not open the file C:\MyProgram\datafile.txt." 
End ' abort the program 

End If 














" Get the various times and dates associated with the file: 

















retval = GetFileTime(hfile, ctime, atime, wtime) 
' Load jantime with the date January 5, 1999 at midnight: 
jantime.wMonth = 1: jantime.wDay = 5: jantime.wYear = 1999 
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jantime.wHour = 0: jantime.wMinute = 0: jantime.wSecond = 0 

" Convert jantime into FILETIME format so it can be compared with ctime: 

retval = SystemTimeToFileTime(jantime, janfiletime) 

" Compare the two times and display the relation: 

comptimes = CompareFileTime(ctime, janfiletime) 

If comptimes = -1 Then Debug.Print "File was created before midnight, January 5, 
1999." 

If comptimes = 0 Then Debug.Print "File was created at midnight, January 5, 1999." 

If comptimes = 1 Then Debug.Print "File was created after midnight, January 5, 1999." 
































' Close the file 
retval = CloseHandle (hfile) 








See Also: FileTimeToSystemTime 





Category: Time 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/systemtimetofiletime.html 
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TextOut Function 


Declare Function TextOut Lib "gdi32.dll1" Alias "TextOutA" (ByVal hdc As Long, 
ByVal x As Long, ByVal y As Long, ByVal lpString As String, ByVal nCount As 
Long) As Long 


Platforms: Win 32s, Win 95/98, Win NT 
TextOut displays a line of text on a device. The relation of the text to the (x,y) pair passed to the function can be set 


using SetTextAlign. The text will be displayed using the device's currently selected font and text drawing color. The 
function returns 1 if successful, or O if an error occured. 


hdc 

The device context of the device to display the line of text on. 
x 

The x coordinate of the reference point to display the text at. 
y 

The y coordinate of the reference point to display the text at. 
lpString 

The string to display on the device. 
nCount 

The size in characters of lpString. 
Example: 


' Display the text "Hello, world!" on window Forml at (100,50). 
" Center the text horizontally at that point and have it appear below the point. 
Dim retval As Long ' return value 








' Set the reference point to be centered horizontally and on the top edge of the 
text: 

retval = SetTextAlign(Forml.hDC, TA_CENTER Or TA_TOP Or TA_NOUPDATECP) 

' Display the text: 

retval = TextOut (Forml.hDC, 100, 50, "Hello, world!", 13) 





See Also: GetTextAlign, SetTextAlign 
Category: Fonts & Text 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/t/textout.html 
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TrackPopupMenu Function 








Declare Function TrackPopupMenu Lib "user32.d11" (ByVal hMenu As Long, ByVal uFlags 
As Long, ByVal x As Long, ByVal y As Long, ByVal nReserved As Long, ByVal hWnd As 
Long, ByVal prcRect As Long) As Long 























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


TrackPopupMenu displays a popup menu at a specified point. The function also tracks the menu, updating the selection 
highlight until the user either selects an item or otherwise closes the menu. By default, the function sends a WM_COMMAND 
message to the parent window, notifying it of the selection. However, flags specified in the uFlags parameter can change this 
behavior. 


Return Value 


If uFlags contains the TRPM_RETURNCMD flag, the function returns the identifier of the menu item that the user selected. If 
an error occurs or the user does not select an item, the function instead returns 0. 


If uFlags does not contain the TRPM_RETURNCMD flag, the function returns a nonzero value if the function is successful. If 
an error occured, the function returns 0. Regardless of uFlags, use the GetLastError to get the error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the popup menu to display and track. 

uFlags 
A combination of the following flags specifying the positioning of the popup menu and other behavior of the function: 
TPM_CENTERALIGN 
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Position the popup menu so that its horizontal center occurs at the coordinate specified by x. 
TPM_LEFTALIGN 
Position the popup menu so that its left edge occurs at the coordinate specified by x. 
TPM_RIGHTALIGN 
Position the popup menu so that its right edge occurs at the coordinate specified by x. 
TPM_BOTTOMALIGN 
Position the popup menu so that its bottom edge occurs at the coordinate specified by y. 
TPM_TOPALIGN 
Position the popup menu so that its top edge occurs at the coordinate specified by y. 
TPM_VCENTERALIGN 
Position the popup menu so that its vertical center occurs at the coordinate specified by y. 
TPM_NONOTIFY 
Do not send a WM_COMMAND message to the popup menu's parent window to notify it of the user's selection. 
TPM_RETURNCMD 
Have TrackPopupMenuEx return the identifier of the menu item that the user selected. 
TPM_LEFTBUTTON 
Only allow the user to select a menu item using the left mouse button (or the keyboard). 
TPM_RIGHTBUTTON 

Allow the user to select a menu item using either mouse button (or the keyboard). 





The x-coordinate of the point where the popup menu is to be displayed, relative to the screen. 
y 
The y-coordinate of the point where the popup menu is to be displayed, relative to the screen. 
hWnd 
A handle to the window that owns the popup menu. This window will receive the WM_COMMAND message. The 
window must be specified even if fuFlags contains the TPM_NONOTIFY flag. 
prcRect 
Ignored -- set to 0. 


Constant Definitions 


































































































Const TPM_CENTERALIGN = &H4 
Const TPM_LEFTALIGN = &HO 
Const TPM _RIGHTALIGN = &H8 
Const TPM _BOTTOMALIGN = &H20 
Const TPM_TOPALIGN = &HO 
Const TPM_VCENTERALIGN = &H10 
Const TPM _NONOTIFY = &H80 
Const TPM _RETURNCMD = &H100 
Const TPM_LEFTBUTTON = &HO 
Const TPM _RIGHTBUTTON = &H2 
Example 


F 


This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function CreatePopupMenu Lib "user32.dl1l" () As Long 

Public Declare Function DestroyMenu Lib "user32.dl1" (ByVal hMenu As Long) As Long 
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ENULITEMINFO 











Public Type M 
cbSiz 
fMask 
fType 
fStat 
wID A 
hSubM 
hbmpC 
hbmpU 
dwite 
dwTyp 
cch A 
End Type 
ublic Con 
ublic Con 
ublic Con 
ublic Con 
ublic Con 
ublic Con 
ublic Con 

















S 
S 
S 
st 
S 
S 








st 








ublic 
ByVal _ 
hMenu 


P 
P 
P 
P 
P 
P 
P 
P 

( 





e As Long 

As Long 

As Long 
e As Long 
s Long 
enu As Long 
hecked As Long 
nchecked As Long 
mData As Long 
eData As String 
s Long 











&H1 





IIM_STATE 
IIM_ID &H2 

IIM_TYPE &H10 
FT_SEPARATOR 
FT_STRING 
FS_DEFAULT 
MFS_ENABLED 


























= &H800 
&HO 
& 


& 








S Ss = iS 4S S 


1000 
0 



































Declare Function InsertMenulItem Lib 








As Long, 





MENUI 








TEMINFO) As Long 








Public 





uFlag 

ByVal _ 
hWnd 
ublic Const 
ublic Const 
ublic Const 
ublic Const 
ublic Const 








Declare Function TrackPopupMenu Lib " 





s As Long, ByVal x As Long, 





As Long, 
TPM_LEFTALIGN 
TPM_TOPALIGN = 
TPM_NONOTIFY = 
TPM_RETURNCMD 
TPM_LEFTBUTTON 





& 
& 


&HO 

0 

80 

&H100 
&HO 















































tg to y to g g 





ublic Type P 
x AS 
y As 

End Type 

Public Declar 








' When the us 
' menu only h 
" needed and 


' The followi 
' identifiers 
they are 

' used just t 
Private Const 
Private Const 
Private Const 











Private Sub C 


OINT TYPE 





Lon 
Lon 


g 
g 





e Function GetCursorPos Lib 








clicks button Commandl, 
two options, 
destroyed after its use. 


er 
as 
is 


ng 
used by this example. 






































o eliminate "magic numbers." 
D_ABOUT = 101 
ID_SEPARATOR = 102 
D_EXIT = 103 
ommand1l_Click () 


ByVal ultem As Long, 


user32.d11" 


Alias 





InsertMenul] 





F 








ByVal 





user32.d11" 


ByPosition As Long, 





( 








ByVal prcRect As Long) 


As Long 


"user32.d11" 





divided by a separator bar. 
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ByVal y As Long, 








lpn 


ByVal hMenu As Long, 
ByVal nReserved As Long, 


(lpPoint As POINT TYPE) 


have a very simple popup menu appear. 


[TtemA" 


nii As _ 





ByVal _ 





As Long 


The 


The menu is created when 


application-defined constants are used to name the menu item 
They are not actually part of the API; 


instead, 


Windows API Guide: TrackPopupMenu Function 
































Dim hPopupMenu As Long ' handle to the popup menu to display 

Dim mii As MENUITEMINFO ' describes menu items to add 

Dim curpos As POINT TYPE ' holds the current mouse coordinates 

Dim menusel As Long ' ID of what the user selected in the popup menu 
Dim retval As Long ' generic return value 














' Create the popup menu that will be displayed. 
hPopupMenu = CreatePopupMenu () 
' Add the menu's first item: "About This Problem..." 
With mii 

' The size of this structure. 

.cbSize = Len (mii) 

















' Which elements of the structure to use. 
.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYP! 
' The type of item: a string. 

.fType = MFT_STRING 

' This item is currently enabled and is the default item. 
.£State = MFS_ ENABLED Or MFS_ DEFAULT 

' Assign this item an item identifier. 

.wID = ID_ABOUT 
' Display the following text for the item. 
.dwTypeData = "&About This Example..." 
.cch = Len(.dwTypeData) 











Cl 

























































































End With 

retval = InsertMenulItem(hPopupMenu, 0, 1, mii) 
" Add the second item: a separator bar. 

With mii 





.fType = MFT_SEPARATOR 
.fState = MFS_ENABLED 
.wID = ID_SEPARATOR 
End With 
retval = InsertMenulItem(hPopupMenu, 1, 1, mii) 
' Add the final item: "Exit". 
With mii 
.£Type= MFT_STRING 
.wID = ID_EXIT 

























































































.dwTypeData = "E&éxit" 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 2, 1, mii) 








' 








Determine where the mouse cursor currently is, in order to have 
the popup menu appear at that point. 
retval = GetCursorPos (curpos) 





' 





' 


Display the popup menu at the mouse cursor. Instead of sending messages 
to window Forml, have the function merely return the ID of the user's 











selection. 


menusel = TrackPopupMenu (hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or 
TPM_NONOTIFY _ 

















Or TPM_RETURNCMD Or TPM_LEFTBUTTON, curpos.x, curpos.y, 0, 











Forml.hWnd, 0) 
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' Before acting upon the user's selection, destroy the popup menu now. 














retval 


DestroyMenu (hPopupMenu) 





Select Case menusel 
Case ID_ABOUT 
' Use the Visual Basic MsgBox function to display a short message in 





a dialog 


display " & 


Guide") 














" box. Using the MessageBox API function isn't necessary. 


retval = MsgBox("This example demonstrates how to use the API to 





"a pop-up menu.", vbOkOnly Or vbInformation, "Windows API 








Case ID_ 





End Sub 





See Also 


TrackPopupMenuEx 


Category 


Menus 





Un 


End Select 


Back to the Function list. 





EXIT 
End this program by closing and unloading Forml. 








load Forml 


Back to the Reference section. 


Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 





E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/t/trackpopupmenu.html 
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TrackPopupMenuEx Function 
Declare Function TrackPopupMenuEx Lib "user32.d11" (ByVal hMenu As Long, ByVal 





























fuFlags As Long, ByVal x As Long, ByVal y As Long, ByVal hwnd As Long, lptpm As 
TPMPARAMS) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


TrackPopupMenuEx displays a popup menu at a specified point. The function also tracks the menu, updating the selection 
highlight until the user either selects an item or otherwise closes the menu. By default, the function sends a WM_COMMAND 


message to the parent window, notifying it of the selection. However, flags specified in the fuFlags parameter can change this 
behavior. 


Return Value 


If fuFlags contains the TRPM_RETURNCMD flag, the function returns the identifier of the menu item that the user selected. If 
an error occurs or the user does not select an item, the function instead returns 0. 


If fuFlags does not contain the TRPM_RETURNCMD flag, the function returns a nonzero value if the function is successful. If 
an error occured, the function returns 0. Regardless of fuFlags, use the GetLastError to get the error code. 


Visual Basic-Specific Issues 


None. 


Parameters 


hMenu 
A handle to the popup menu to display and track. 

fuFlags 
A combination of the following flags specifying the positioning of the popup menu and other behavior of the function: 
TPM_CENTERALIGN 
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hwnd 


lptpm 


Position the popup menu so that its horizontal center occurs at the coordinate specified by x. 
TPM_LEFTALIGN 
Position the popup menu so that its left edge occurs at the coordinate specified by x. 
TPM_RIGHTALIGN 
Position the popup menu so that its right edge occurs at the coordinate specified by x. 
TPM_BOTTOMALIGN 
Position the popup menu so that its bottom edge occurs at the coordinate specified by y. 
TPM_TOPALIGN 
Position the popup menu so that its top edge occurs at the coordinate specified by y. 
TPM_VCENTERALIGN 
Position the popup menu so that its vertical center occurs at the coordinate specified by y. 
TPM_NONOTIFY 
Do not send a WM_COMMAND message to the popup menu's parent window to notify it of the user's selection. 
TPM_RETURNCMD 
Have TrackPopupMenuEx return the identifier of the menu item that the user selected. 
TPM_LEFTBUTTON 
Only allow the user to select a menu item using the left mouse button (or the keyboard). 
TPM_RIGHTBUTTON 
Allow the user to select a menu item using either mouse button (or the keyboard). 
TPM_HORIZONTAL 
If the popup menu cannot be shown at the desired coordinates without intruding upon the exclusion rectangle, 
preserve the horizontal positioning instead of the vertical. 
TPM_VERTICAL 
If the popup menu cannot be shown at the desired coordinates without intruding upon the exclusion rectangle, 
preserve the vertical positioning instead of the horizontal. 





The x-coordinate of the point where the popup menu is to be displayed, relative to the screen. 
The y-coordinate of the point where the popup menu is to be displayed, relative to the screen. 


A handle to the window that owns the popup menu. This window will receive the WM_COMMAND message. The 
window must be specified even if fuFlags contains the TPM_NONOTIPY flag. 








Specified additional information about the positioning of the popup menu, specifically regarding the exclusion rectange. 
The exclusion rectangle is a region of the screen in which the popup menu will not appear. 


Constant Definitions 


Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 
Con 





Con 


AN HA NHA HANA AHnNHHAAN HN DN 


cr ocr oof er choc cf er ocr opr ocr oat 








TPM_CENTERALIGN = &H4 
TPM_LEFTALIGN = &HO 
TPM_RIGHTALIGN = &H8 
TPM_BOTTOMALIGN = &H20 
TPM_TOPALIGN = &HO 
TPM _VCENTERALIGN = &H10 
TPM_NONOTIFY = &H80 
TPM_RETURNCMD = &H100 
TPM_LEFTBUTTON = &HO 
TPM_RIGHTBUTTON = &H2 
TPM_HORIZONTAL = &HO 

















































































































TPM_VERTICAL = &H40 
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Example 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 


' (Copy them to the (declarat 
Public Declare Function Creat 











ions) section of a module.) 


ePopupMenu Lib "user32.dl11" () 











Public Declare Function Destr 
Public Type MENUITEMINFO 
cbhSize As Long 








oyMenu Lib "user32.d1l1" (ByVal hMenu As Long) 




















fMask As Long 
fType As Long 
fState As Long 


wID As Long 

hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 
cch As Long 











End Type 

Public Con 
Public Con 
Public Con 
Public Con 
Public Con 
Public Con 
P 
P 
( 


emp ee ee ee 

















ByVal 


ublic Const 
ublic Declare Function InsertMenulItem Lib "user32.d1l1" Alias "InsertMenulItemA" 











IIM_STATE = &H1 
IIM_ID = &H2 

IIM_TYPE = &H10 
FT_SEPARATOR = 
FT_STRING = &HO 
FS DEFAULT = & 


MFS_ENABLED = & 



































<= SS 1s 3s = 



































&H800 


1000 
0 


ns and conditions listed here. 


As Long 


























hMenu As Long, ByVal 








MENUITEMINFO) As Long 














Public Type RECT 





left As Long 
top As Long 
right As Long 
bottom As Long 





End Type 


Public Type TPMPARAMS 


cbhSize As Long 
rcExclude As RECT 








End Type 








As Long 


uItem As Long, ByVal fByPosition As Long, lpmii As _ 


Public Declare Function TrackPopupMenuEx Lib "user32.d11" 





As 





fuFlags As Long, ByVa 


TPMPARAMS) As Long 


Public Const 


Public Const 





Public Const 





TPM_LEFTALIGN = 














1 x As Long, ByVal y As Long, 


&HO 





TPM_TOPALIGN = & 





0 











TPM_NONOTIFY = & 


80 
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(ByVal hMenu As Long, 





ByVal hWnd As Long, 


ByVal 





lptpm 


Windows API Guide 


: TrackPopupMenuEx Function 























Public Const TPM _RETURNCMD = &H100 
Public Const TPM_LEFTBUTTON = &HO 
Public Type POINT TYPE 
































x As Long 

y As Long 
End Type 
Public Declare Function GetCursorPos Lib "user32.dl1" (lpPoint As POINT TYPE) 
Public Declare Function SetRectEmpty Lib "user32.d11" (lpRect As RECT) As Long 
' When the user clicks button Commandl, have a very simple popup menu appear. 


' menu only has 
" needed and is 


' The following 








two options, 
destroyed after 








divided 

















by a separator bar. 


its use. 







































































































































































application-defined constants are used to name the menu item 


As Long 


The 


The menu is created when 


stead, 


' identifiers used by this example. They are not actually part of the API; in 
they are 
' used just to eliminate "magic numbers." 
Private Const ID ABOUT = 101 
Private Const ID SEPARATOR = 102 
Private Const ID_EXIT = 103 
Private Sub Command1_Click () 
Dim hPopupMenu As Long ' handle to the popup menu to display 
Dim mii As MENUITEMINFO ' describes menu items to add 
Dim tpm As TPMPARAMS ' identifies the exclusion rectangle 
Dim curpos As POINT TYPE ' holds the current mouse coordinates 
Dim menusel As Long ' ID of what the user selected in the popup menu 
Dim retval As Long ' generic return value 
' Create the popup menu that will be displayed. 
hPopupMenu = CreatePopupMenu () 
' Add the menu's first item: "About This Problem..." 
With mii 
' The size of this structure. 
.cbSize = Len (mii) 
' Which elements of the structure to use. 
.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' The type of item: a string. 
.fType = MFT_STRING 
' This item is currently enabled and is the default item. 
-£fState = MFS_ ENABLED Or MEFS DEFAULT 
' Assign this item an item identifier. 
.wID = ID_ABOUT 
' Display the following text for the item. 
-dwTypeData = "&About This Example..." 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 0, 1, mii) 
' Add the second item: a separator bar. 
With mii 
.£Type = MFT_SEPARATOR 
.fState = MFS_ENABLED 
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End Wi 
retval 
' Add 

With m 








End Wi 
re 





" Det 


D 





ID 








wl 
th 


LS 














the final item: 


ii 








.fType= 
.WID ID_EX 
.dwTypeData = 
Jeen 

th 

















T 











tval = InsertMenuItem(hPopupMenu, 








rmin 








= InsertMenultem (hPopupMenu, 


MFT_STRI 


m 
Es 


E&xit" 
Len (.dwTypeData) 


where the mouse cursor currently is, 


EPARATOR 


1, 1, mii) 


Exit"; 


NG 





2, dy mii) 


in order to have 





' the popup menu appear at that point. 


retval 


$ 





Make the exclusion rectangle empty becaus 











GetCursorPos (curpos) 


there's no need for it here. 




















With tpm 
' Size of the structure. 
.cbSize = Len (tpm) 
' Make the exclusion rectangle empty. 
retval = SetRectEmpty (.rcExclude) 
End With 








' Display the popup menu at 



































the mouse cursor. Instead of sending messages 















































' to window Forml, have the function merely return the ID of the user's 
selection. 
menusel = TrackPopupMenuEx (hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or 
TPM_NONOTIFY _ 
Or TPM_RETURNCMD Or TPM_LEFTBUTTON, curpos.x, curpos.y, Forml.hWnd, 
tpm) 
' Before acting upon the user's selection, destroy the popup menu now. 
retval = DestroyMenu (hPopupMenu) 
Select Case menusel 
Case ID_ABOUT 
' Use the Visual Basic MsgBox function to display a short message in 
a dialog 
' box. Using the MessageBox API function isn't necessary. 
retval = MsgBox("This example demonstrates how to use the API to 
display " & _ 
"a pop-up menu.", vbOkOnly Or vbInformation, "Windows API 
Guide") 
Case ID_EXIT 








End Sub 





See Also 











Unload Forml 


End Select 


End this program by closing and unloading Forml. 
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TrackPopupMenu 





Category 


Menus 


Back to the Function list. 
Back to the Reference section. 





Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/t/trackpopupmenuex.html 
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UnionRect Function 








Declare Function UnionRect Lib "user32.d1l1" (lpDestRect As RECT, lpSrclRect As RECT, 
lpSrc2Rect As RECT) As Long 


Platforms: Win 32s, Win 95/98, Win NT 


UnionRect determines the smallest possible rectangle that contains two other rectangles. This rectangle is called the union 
rectangle because it is derived from the union of the areas that the two source rectangles occupy. The union rectangle is put 
into the variable passed as /pDestRect. The function returns 0 if an error occured, or 1 if successful. 


[pDestRect 

Variable that receives the union rectangle. 
IpSrclRect 

The first of the two source rectangles. 
IpSrc2Rect 

The second of the two source rectangles. 


Example: 
' Create a large rectangle that contains the areas occupied by 

' rectangles s and t. The new rectangle will fully contain both smaller rectangles. 
' s = (20,30)-(60,80); t = (100,110)-(200, 300) 

Dim s As RECT, t As RECT ' small rectangles 

Dim urect As RECT ' receives the union rectangle 




















Dim retval As Long ' return value 





' Set the small rectangles 
retval = SetRect(s, 20, 30, 60, 80) " set s = (20,30)-(60, 80) 
retval = SetRect(t, 100, 110, 200, 300) ' set t = (100,110)-(200, 300) 





Figure out the union rectangle 
retval = UnionRect (urect, s, t) " now urect = (20,30)-(200, 300) 


See Also: IntersectRect, SubtractRect 
Category: Rectangles 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/u/unionrect.html 
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shop.com | 
UnregisterClass Function 
Declare Function UnregisterClass Lib "user32.d11" Alias "UnregisterClassA" (ByVal 








lpClassName As Any, ByVal hInstance As Long) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


UnregisterClass unregisters a window class, after which it can no longer be used. Obviously, a window class cannot be 
unregistered if windows still exist which belong to the class. All window classes created by an application should be 
unregistered after the application is completely finished using them. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non- 
zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpClassName 
The name of the window class to unregister, or an atom identifying the window class to unregister. 


hInstance 
A handle to the instance which originally registered the window class. 


Example 


' This code is licensed according to the terms and conditions listed here. 
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' Register a new window class. The various properties to 
' give it will be explained in the code. 





' *** Place the following code in a module. *** 

' Define the window procedure to use for the class. Here, we'll 

' just make a wrapper for the default window procedure. 

Public Function WindowProc (ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As 





Long, ByVal lParam As Long) As Long 
' Return whatever the default window procedure returns. 
WindowProc = DefWindowProc(hWnd, uMsg, wParam, lParam) 











End Function 


' xxx Place the following code where you want to register the class. *** 
Dim classinfo As WNDCLASSEX ' holds info about the class 


Dim classatom As Long ' receives an atom to the class just registered 














' Set the various data members of the structure. 

' Of course, set the size of the structure. 

classinfo.cbSize = Len(classinfo) 

' Class style: give each window its own DC; redraw when resized. 
classinfo.style = CS_OWNDC Or CS_HREDRAW Or CS_VREDRAW 

Use the window procedure above to process messages. 
classinfo.lpfnWndProc = AddressOf WindowProc 




















We aren't using any extra information. 





classinfo.cbClsExtra = 0 
classinfo.cbWndExtra = 0 

' Handle to the instance of this application. 
classinfo.hInstance = App.hInstance 





Use the icon stored in C:\MyApp\deficon.ico. 
classinfo.hIcon = ExtractIcon(App.hInstance, "C:\MyApp\deficon.ico", 0) 

















Use the cursor stored in C:\MyApp\mouse.cur. 
classinfo.hCursor = LoadCursorFromFile ("C:\MyApp\mouse.cur") 





Fill the background with the system color for an application's workspace. 
classinfo.hbrBackground = COLOR_APPWORKSPACE 

' No menu resource to use. 

lassinfo.lpszMenuName = "" 

Give the class a name. 

lassinfo.lpszClassName = "CustomClass" 

Use the small icon stored in C:\MyApp\deficonsm.ico. 

classinfo.hIconSm = ExtractIcon(App.hInstance, "C:\MyApp\deficonsm.ico", 0) 





Q 











=g 























' Finally, register the class. 
classatom = RegisterClassEx(classinfo) 











' Now the class CustomClass can be used to create windows. 





' *** Place the following code where you wish to unregister the window class. *** 
Dim retval As Long 








' Unregister the window class. 
retval = UnregisterClass ("CustomClass", App.hInstance) 
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See Also 


RegisterClass, RegisterClassEx 





Category 


Window Classes 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: August 24, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/u/unregisterclass.html 
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VerQueryValue Function 








Declare Function VerQueryValue Lib "version.dll" Alias "VerQueryValueA" (pBlock As 
Any, ByVal lpSubBlock As String, lplpBuffer As Long, puLen As Long) As Long 


























Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


VerQuery Value extracts information from a version information resource. This resource stores version-related information 
about a 32-bit executable-type file. The GetFileVersionInfo function obtains this resource from the desired file. 


VerQueryValue can get both general version information and version identifying strings from the resource. Naturally, since 
version information resources do not exist for non-32-bit applications, nor for non-executable files, this function will not work 
with them. 


Return Value 


If successful, the function returns a non-zero value. If an error occured, the function returns 0. 


Visual Basic-Specific Issues 


To actually use the information retrieved by VerQueryValue, you have to copy the data identified by the pointer /plpBuffer 
into the appropriate object. To do this, use Istrcpy for strings and CopyMemory for anything else. For the root block, copy the 
pointer's data into a VS_ FIXEDFILEINFO structure. For the code page and language data, copy the data into a four-element 
Byte array. For version information strings, copy the data into, you guessed it, a string. 








If you're a bit confused or overwhelmed, don't be. The example on this page illustrates how to do all three. 


Parameters 


pBlock 
The byte array or similar object that holds the version information resource extracted from a file. To obtain such a 
block, use GetFile VersionInfo. 

lpSubBlock 
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One of the following strings specifying what information to extract from the resource. A pointer to the extracted 
information is placed into /plpBuffer. 
mw" 

Extract the root block of version information, which is in the form of a VS_FIXEDFILEINFO structure. 
"\WVarFileInfo\Translation" 


Extract the identifier of the language and code page in which the version information strings are encoded. While 
this is not useful in and of itself, this data is necessary to read any version information strings in the resource. 
See Note | below for details about how to use this value. 
"\StringFileInfo\lang-codepage\string-name" 
Extract one of the version information strings in the resource. lang-codepage is an 8-digit hexadecimal value 
that identifies the code page and language used to encode the string. string-name is one of the following values 
that identify the various strings available: 
"Comments" 
"CompanyName" 
"FileDescription" 
"File Version" 
"InternalName" 
"LegalCopyright" 
"LegalTrademarks" 
"OriginalFilename" 
"PrivateBuild" 
"ProductName" 
"ProductVersion" 
"SpecialBuild" 








lplpBuffer 
Receives a pointer to the data extracted from the version information resource. The memory referenced by this pointer 


is automatically freed when the memory used by pBlock is freed. In other words, don't worry about freeing this memory 
after you use it. 
puLen 


Receives the size in bytes of the data referenced by the /plpBuffer pointer. 


Note 1 


The code page and language data comes as a series of four bytes. Before using the data, however, it needs to be modified 
slightly. You must swap the first two bytes with each other, and then swap the last two with each other. Then, you need to 
convert the four bytes into an 8-digit hexadecimal string, with the first byte (after the swap) at the beginning and the last byte 
at the end. For example, if "00" represents the first byte, "11" the second, etc., the string will look like "00112233". You are 
now ready to use this string as the lang-codepage component of a version information string identifier. Go back up. 


Example 


Display information about the file whose full path and filename is entered into textbox Text1. Display the version number, 
copyright information, and file description when button Command! is pressed. To use this example, you obviously have to 
enter the filename of a 32-bit executable/DLL/etc. into Text1. Obviously, this example requires that you create a text box 
called Textl and a command button called Command1. 


This code is licensed according to the terms and conditions listed here. 


E 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
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Public Declare Function GetFileVersionInfo Lib "version.dll" Alias 








"GetFileVersionInfoA" _ 
(ByVal lptstrFilename As String, ByVal dwHandle As Long, ByVal dwLen As Long, 





























lpData As Any) As Long 
Public Declare Function GetFileVersionInfoSize Lib "version.dl1l" Alias _ 











"GetFileVersionInfoSizeA" (ByVal lptstrFilename As String, lpdwHandle As 
Long) As Long 
Public Declare Function VerQueryValue Lib "version.dll" Alias "VerQueryValueA" 
(epBlock _ 
As Any, ByVal lpSubBlock As String, lplpBuffer As Long, puLen As Long) As 




















Long 
Public Declare Function Ilstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 

















As Any, ByVal lpString2 As Any) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 











As Any, _ 
Source As Any, ByVal Length As Long) 
Public Type VS_FIXEDFILEINFO 
dwSignature As Long 
dwStrucVersion As Long 
dwFileVersionMS As Long 
dwFileVersionLS As Long 
dwProductVersionMS As Long 
dwProductVersionLsS As Long 
dwFileFlagsMask As Long 
dwFileFlags As Long 
dwFileOS As Long 
dwFileType As Long 
dwFileSubtype As Long 
dwFileDateMS As Long 
dwFileDateLS As Long 
End Type 


















































Public Const VFT_APP = &H1 
Public Const VFT_DLL = &H2 
Public Const VFT_DRV = &H3 
Public Const VFT_VXD = &H5 




















' ***x Place the following function definitions inside a module. *** 





' HIWORD and LOWORD are API macros defined below. 
Public Function HIWORD (ByVal dwValue As Long) As Long 
Dim hexstr As String 
hexstr = Right ("00000000" & Hex(dwValue), 8) 
HIWORD = CLlng("&H" & Left(hexstr, 4)) 
End Function 
Public Function LOWORD (ByVal dwValue As Long) As Long 
Dim hexstr As String 
hexstr = Right ("00000000" & Hex(dwValue), 8) 
LOWORD = CLng("&H" & Right (hexstr, 4)) 
End Function 
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i 





This nifty subroutine swaps two byte values wi 
which uses Xor, 
the same data type 


This technique, 


numeric 








and of 








Public Sub SwapByte 





F 





bytel 
byte2 
bytel 
End Sub 
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(bytel As 
bytel 
= bytel 
bytel 














Byte, 


Xor byte2 
Xor byte2 
Xor byte2 


























(here, 
byte2 As 


bo 








thout needing a buffer variable. 


works as long as the two values to be swapped are 
th 
Byte) 





Byte). 





















































This function creates a hexadecimal string to represent a number, but it 
outputs a string of a fixed number of digits. Extra zeros are added to make 
the string the proper length. The "&H" prefix is not put into the string. 
Public Function FixedHex (ByVal hexval As Long, ByVal nDigits As Long) As String 
FixedHex = Right ("00000000" & Hex(hexval), nDigits) 
End Function 
xxx Place the following code inside the form that has Commandl and Textl. *** 
Private Sub Command1_Click () 
Dim vffi As VS FIXEDFILEINFO ' version info structure 
im buffer() As Byte ' buffer for version info resource 
im pData As Long ' pointer to version info data 
im nDataLen As Long ' length of info pointed at by pData 


then Textl 

















nD 
If 


T 
EN 
' 





Re 


retval = GetFileVersionInfo (Textl.Text, 


ie 
' 


CopyMemory vffi, 


' 


di 








m re 


First, 


m cpl(0 To 3) 
m cplstr As String 
m dispstr As String 
tval As Long 


As 





Byte 








' buf 





fer for code page & language 





' 8-digit hex string of cpl 
' string used to display version information 
' generic return value 


get the size of the version in 














this function fails, 








fo resource. 











identifies a file that isn't a 32-bit executable/DLL/etc. 


ataL 





n = GetFileVersionInfoSize(Textl.Text, 











nDataLen 





Exit 
a If 


O Then 


Debug.Print 


Sub 





pData) 


"Not a 32-bit executable!" 


Make the buffer large enough to hold the version info resource. 








Dim buffer (0 To nl 





DataLen 


As 





1) 


By 


Ce 


Get the version information resource. 








Get a pointer to a str 
VerQueryValue (b 


tval 








u 


ucture that holds a bunch of 
ffer (0), 


MAM 











0, nDataLen, buffer (0)) 


data. 
DataLen) 











Data, n 


P 


Copy that structure into the one we can access. 








ByVal 


P 








Display th 





Data, 





n 


DataLen 


e full version number of the file. 





De 





spstr 
Trim 
Trim 
Trim 


bug.Print 


"Version 








Display th 


e type of file it is 





Trim(Str (HIWORD (v 
(Str (LOWORD (vffi 
(Str (HIWORI 
(Str (LOWOR 














D (v 


umber 











N 


D (vffi 


ee 2 


£ 














.dwFileVersionMS) 
.dwFileVersionLs) 





.dwFil 


fi.dwFileVersionM 


eVersionLs) 


) & Ww ` " 
& " . W 
& 


S)) 
)) 
)) 
)) 





"; dispstr 


(i.e., 





executable, DLL, etc.). 
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Select Case vffi.dwFileType 
Case VFT_APP 






































dispstr = "Application" 
Case VFT_DLL 
dispstr = "Dynamic Link Library (DLL)" 
Case VFT_DRV 
dispstr = "Device Driver" 
Case VFT_VXD 
dispstr = "Virtual Device Driver" 
Case Else 
dispstr = "Unknown" 
End Select 








Debug.Print "File Type: "; dispstr 


$ 





Before reading any strings out of the resource, we must first determine th 








code page 
' and language. The code to get this information follows. 
retval = VerQueryValue (buffer (0), "\VarFileInfo\Translation", pData, 
DataLen) 
' Copy that informtion into the byte array. 
CopyMemory cpl(0), ByVal pData, 4 
' It is necessary to swap the first two bytes, as well as the last two bytes. 
SwapByte cpl(0), cpl(1) 
SwapByte cpl(2), cpl (3) 
" Convert those four bytes into a 8-digit hexadecimal string. 
cplstr = FixedHex(cpl(0), 2) & FixedHex(cpl(1), 2) & FixedHex(cpl(2), 2) & 
FixedHex(cpl(3), 2) 
cplstr now represents the code page and language to read strings as. 




















5) 









































' Read the copyright information from the version info resource. 
retval = VerQueryValue (buffer (0), "\StringFileInfo\" & cplstr & 

"\LegalCopyright", 

pData, nDataLen) 

Copy that data into a string for display. 

dispstr = Space (nDataLen) 

retval = lstrcpy(dispstr, pData) 

' Display the result. 

Debug.Print "Copyright Info: "; dispstr 

' Similarly, read a description of the file and display it. 
retval = VerQueryValue (buffer(0), "\StringFileInfo\" & cplstr & 

"\FileDescription", 





























' 



























































pData, nDataLen) 
dispstr = Space (nDataLen) 
retval = lstrcpy(dispstr, pData) 
Debug.Print "File Description: "; dispstr 








End Sub 





See Also 


GetFileVersionInfo, GetFileVersionInfoSize 





http://216.26.168.92/vbapi/ref/v/verqueryvalue.html (5 of 6) [9/1/2002 5:52:58 PM] 


Windows API Guide: VerQuery Value Function 
Category 
Files 


Back to the Function list. 
Back to the Reference section. 


Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/v/verqueryvalue.html 
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WaitForSingleObject Function 


Declare Function WaitForSingleObject Lib "kernel32.d1l1" (ByVal hHandle As Long, 
ByVal dwMilliseconds As Long) As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WaitForSingleObject halts program execution temporarily, until either a specified object enters a signaled state or a 
specified timeout period elapses. This function allows a program to wait until something else has happened before execution 
continues. 


Return Value 


The function returns one of the following flags: 


WAIT_ABANDONED 
The mutex specified by hHandle was not released by its owning thread before that thread terminated. The mutex is 
now owned by the calling thread and is in a nonsignaled state. 

WAIT_FAILED 
The function failed. Use GetLastError to get the error code. 


WAIT_OBJECT_0 

The object specified by hHandle is in a signaled state. 
WAIT_TIMEOUT 

The timeout period has elapsed. 


Visual Basic-Specific Issues 


None. 


Parameters 
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hHandle 
A handle to the object to wait for to enter into a signaled state. This handle can refer to one of the following types of 
objects: 
o Change Notification 
o Console Input 
o Event 
o Job (is signaled when the job has finished) 
o Mutex 
o Process (is signaled when the process has terminated) 
o Semaphore 
o Thread (is signaled when the thread has terminated) 
o Waitable timer 
dwMilliseconds 
The timeout interval to wait for. The function will return (with a value of WAIT_TIMEOUT) if this timeout period 
elapses, even if the object being waited for has not entered a single state. This parameter could also be the following 
value: 
INFINITE 
Wait forever -- do not use a timeout period. 


Constant Definitions 


Const WAIT_ABANDONED = &80 
Const WAIT_FAITLED = &HFFFFFFFF 
Const WAIT_OBJECT_0O = &HO 
Const WAIT_TIMEOUT = &H102 
Const INFINITE = &HFFFF 




















Example 


Open the file "C:\Docs\readme.txt" using whatever program is associated with *.txt files (by default, Notepad). Wait until the 
user has closed the window before continuing with the example. The example begins when the user clicks button Command 1. 
Obviously, to use this example, you need to place a command button named Command! on a form window. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type SHELLEXECUTEINFO 
cbSize As Long 
fMask As Long 
hwnd As Long 
lpVerb As String 
lpFile As String 
lpParameters As String 
lpDirectory As String 
nShow As Long 
hinstApp As Long 
lpIDList As Long 


lpClass As String 
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hkeyClass As Long 
dwHotKey As Long 
hicon As Long 
hProcess As Long 
End Type 
Public Const SEE_MASK_NOCLOSEPROCESS = &H40 
Public Const SW_SHOWNORMAL = 1 
Public Declare Function ShellExecuteEx Lib "shel132.d11" Alias "ShellExecuteExA" 
(lpExecInfo As _ 
SHELLEXECUTEINFO) As Long 
Public Const SE_ERR_FNF = 2 
Public Const SE_ERR_NOASSOC = 31 
Public Declare Function WaitForSingleObject Lib "kernel32.dll" (ByVal hHandle As 
Long, ByVal _ 
dwMilliseconds As Long) As Long 
Public Const INFINITE = &HFFFF 
Public Const WAIT_TIMEOUT = &H102 


















































' *** Place the following code inside window Forml. *** 
Private Sub Command1_Click () 


Dim sei As SHELLEXECUTEINFO ' structure used by the function 
Dim retval As Long ' return value 























' Load the information needed to open C:\Docs\readme.txt 
' into the structure. 





















































With sei 
' Size of the structure 
.cbSize = Len (sei) 
' Use the optional hProcess element of the structure. 
.fMask = SEE MASK NOCLOSEPROCESS 
' Handle to the window calling this function. 
-hwnd = Forml.hWnd 
' The action to perform: open the fil 
-lpVerb = "open" 
' The file to open. 
.lpFile = "C:\Docs\readme.txt" 
' No additional parameters are needed her 
.lpParameters = "" 
' The default directory -- not really necessary in this case. 
.lpDirectory = "C:\Docs\" 
' Simply display the window. 
-nShow = SW_SHOWNORMAL 
' The other elements of the structure ar ither not used 
' or will be set when the function returns. 
End With 
' Open the file using its associated program. 
retval = ShellFExecuteEx (sei) 
If retval = 0 Then 


' The function failed, so report the error. Err.LastDllError 
' could also be used instead, if you wish. 








http://216.26.168.92/vbapi/ref/w/waitforsingleobject.html (3 of 4) [9/1/2002 5:53:00 PM] 


Windows API Guide: WaitForSingleObject Function 


Select Case sei.hInstApp 
Case SE_ERR_FNF 


Case SE _NOASSOC 
Case Else 


Debug.Print "An unexpected error occured." 
End Select 








Else 


' Wait for the opened process to close before continuing. 


Debug.Print "The file C:\Docs\readme.txt was not 


Debug.Print "No program is associated with *.txt 


E 


found." 


a= 


files." 





Instead 


' of waiting once for a time of INFINITE, this example repeatedly 





checks to see if the 














has just 


' is still open. This allows the DoEvents VB function to be called, 
preventing 
' our program from appearing to lock up while it waits. 
Do 
DoEvents 
retval = WaitForSingleObject (sei.hProcess, 
Loop While retval = WAIT_TIMEOUT 
Debug.Print "Notepad (or whatever program was opened) 
closed." 
End If 
End Sub 


Category 


Synchronization 


Back to the Function list. 
Back to the Reference section. 


Last Modified: October 29, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/waitforsingleobject.html 
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waveOutGetDevCaps Function 








Declare Function waveOutGetDevCaps Lib "winmm.dll" Alias "waveOutGetDevCapsA" 
(ByVal uDeviceID As Long, lpCaps As WAVEOUTCAPS, ByVal uSize As Long) As Long 























Platforms: Win 95/98, Win NT 


waveOutGetDevCaps reads the capabilities and other information about a given waveform output device. This 
information is placed in the structure passed as /pCaps. This function can determine what operations a waveform output 
device can perform. The function returns 0 if successful, or a non-zero error code if an error occured. 


uDevicelD 
The device identifier of the waveform output device to get information about. Remember that the first device has 
an identifier of 0. 
lpCaps 
Receives the information about the waveform output device. 
uSize 
The size in bytes of [pCaps. 


' List the names and number of channels of every installed waveform output 


' device. Note how we only check the valid device identifiers. 




















Dim outinfo As WAVEOUTCAPS ' receives info about each device 
Dim numdevs As Long ' number of installed devices 

Dim thisdev As Long ' counter for which device we're checking 
Dim outname As String ' buffer for device's name 

Dim retval As Long ' return value 

' First, determine the number of waveform output devices. 





numdevs = waveOutGetNumDevs () 








Loop through each device and display the desired information. Keep in mind that 
the first 
' device has an identifier of 0, etc. 
For thisdev = 0 To numdevs - 1 
' Get the capabilities of the device 
retval = waveOutGetDevCaps (thisdev, outinfo, Len(outinfo) ) 
If retval = 0 Then ' only continue if the above function succeeded 
Debug.Print "Device #"; thisdev 
' Extract device name from fixed-length string 




















outname = Left (outinfo.szPname, InStr(outinfo.szPname, vbNullChar) - 1) 
Debug.Print " "; outname; 
' Display number of channels -- i.e., is it mono or stereo? 
If outinfo.nChannels = 1 Then 
Debug.Print " (mono)" 
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Else 
Debug.Print " (stereo) " 
End If 
End If 
Next thisdev 











Category: Audio 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/w/waveoutgetdevcaps.html 
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waveOutGetNumDevs Function 
Declare Function waveOutGetNumDevs Lib "winmm.dll" () As Long 








Platforms: Win 95/98, Win NT 


waveGetNumDevs find the number of waveform output devices installed on the computer. This function can be used to 
determine the valid range in device identifiers for waveform output devices. The function returns the number of installed 
waveform output devices. 


Example: 


' List the names and number of channels of every installed waveform output 


' device. Note how we only check the valid device identifiers. 

















Dim outinfo As WAVEOUTCAPS ' receives info about each device 
Dim numdevs As Long ' number of installed devices 

Dim thisdev As Long ' counter for which device we're checking 
Dim outname As String ' buffer for device's name 

Dim retval As Long ' return value 

' First, determine the number of waveform output devices. 





numdevs = waveOutGetNumDevs () 
' Loop through each device and display the desired information. Keep in mind that 
the first 
" device has an identifier of 0, etc. 
For thisdev = 0 To numdevs - 1 
' Get the capabilities of the device 
retval = waveOutGetDevCaps (thisdev, outinfo, Len(outinfo) ) 








If retval = 0 Then ' only continue if the above function succeeded 
Debug.Print "Device #"; thisdev 
' Extract device name from fixed-length string 























outname = Left (outinfo.szPname, InStr(outinfo.szPname, vbNullChar) - 1) 
Debug.Print " "; outname; 
' Display number of channels -- i.e., is it mono or stereo? 
If outinfo.nChannels = 1 Then 
Debug.Print " (mono) " 
Else 
Debug.Print " (stereo)" 
End If 
End If 





Next thisdev 
Category: Audio 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/w/waveoutgetnumdevs.html 
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waveOutGetVolume Function 
Declare Function waveOutGetVolume Lib "winmm.dll" (ByVal uDeviceID As Long, 


lpdwVolume As Long) As Long 
Platforms: Win 95/98, Win NT 


waveOutGetVolume finds the current volume setting for a waveform output device. The volume setting is placed in the 
variable passed as /pdwVolume and is split into a high-order word and a low-order word. If the device supports separate left 
and right channel volumes, the low-order word contains the left volume and the high-order word contains the right volume. If 
it does not, the low-order word contains the overall volume and the high-order word is ignored. Volume values range from 
silence (&HO) to maximum (&HFFFF). The function returns 0 if successful, or a non-zero error code if an error occured. 


uDeviceID 

Either the device ID or a handle to the waveform output device to poll the volume of. 
IpdwVolume 

Receives the volume setting of the device as described above. 


Example: 


T F= 


Display the current volume setting for waveform output device 0. Note 
that we must first determine if separate volumes are returned or not, in order to 
know 





























' how to interpret the volume returned. (We assume waveform output device #0 
exists.) 

Dim volume As Long ' receives volume (s) 

Dim lvolume As Long, rvolume As Long ' separate channel volumes 

Dim spkrcaps As WAVEOUTCAPS ' needed to find volume interpretation 

Dim numvols As Integer ' will be 1 if only one volume setting or 2 if there are two 
Dim retval As Long ' return value 

' First, find out whether the left and right channels have separate volumes. 


























retval = waveOutGetDevCaps(0, spkrcaps, Len(spkrcaps) ) ' get information 
If (spkrcaps.dwSupport And WAVECAPS_LRVOLUME) = WAVECAPS_LRVOLUME Then 
numvols = 2 ' separate channel volumes 
Else 
numvols = ] ' only one volume 
End If 





' Get the volume setting(s) and display them in hexadecimal. 
retval = waveOutGetVolume (0, volume) 








If numvols = 1 Then ' if only one channel volume 
volume = volume And &HFFFF ' destroy irrelevant high-order word 
Debug.Print "Waveform Output Device #0 volume: "; Hex(volume) 
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Else ' if separate channel volumes 
lvolume = volume And &HFFFF ' isolate left speaker volume 
rvolume = (volume And &HFFFFO000) / &H10000 ' isolate right speaker volume 
Debug.Print "Waveform Output Device #0 left channel volume: "; Hex(lvolume) 
Debug.Print "Waveform Output Device #0 right channel volume: "; Hex (rvolume) 
End If 


See Also: waveOutSet Volume 
Category: Audio 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 








This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/waveoutgetvolume.html 
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waveOutSetVolume Function 
Declare Function waveOutSetVolume Lib "winmm.dl1l" (ByVal uDeviceID As Long, ByVal 

















dwVolume As Long) As Long 
Platforms: Win 95/98, Win NT 


waveOutSetVolume sets the volume level for a waveform output device. Depending on the capabilities of the device, this 
function either sets the independent left and right channel volumes or the overall volume. Each volume setting must be in 
the range between &HO (silence) and & HFFFF (maximum volume). The function returns 0 if successful, or a non-zero error 
code if and error occured. 


uDevicelD 
Either the device identifier or a handle to the waveform output device to set the volume of. 

dwVolume 
The new volume setting(s) for the device. If separate left/right volumes are supported, the low-order word is the left 
channel volume and the high-order word is the right channel volume. If not, the low-order word contains the overall 
volume and the high-order word is ignored. 


Example: 


' Set the volume on waveform output device #0 to 50% of maximum. 

" Note how we don't care if there are separate volumes or not -- we set both to the 
' setting and, if only one channel volume exists, the extra data is ignored. 

Dim retval As Long ' return value 








' First, verify that waveform output device #0 does exist. 
retval = waveOQutGetNumDevs () " get number of such devices 











If retval >= 1 Then ' at least one exists, so device #0 is there! 

' Set the volume for all channels to &H7FFF (508%) 

retval = waveOutSetVolume(0, &H7FFF7FFF) ' for both channels, if needed 
End If 








See Also: waveOutGetVolume 
Category: Audio 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/w/waveoutsetvolume.html 
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WindowFromPoint Function 
Declare Function WindowFromPoint Lib "user32.dl11" (ByVal xPoint As Long, ByVal 











yPoint As Long) As Long 
Platforms: Win 32s, Win 95/98, Win NT 


WindowFromPoint determines the handle of the window located at a specific point on the screen. Note that the active 
window could be a text box, list box, button, or some other object sitting inside a program window. In this case, the handle 
returned will be to this control and not the program window. If successful, the function returns the handle to the window at 
that point. If there is no window at that point, or if an error occured, the function instead returns 0. 


xPoint 

The x-coordinate of the point to look for a window at. 
yPoint 

The y-coordinate of the point to look for a window at. 


Example: 





' Display the title bar text of whatever window the mouse 




















" cursor is currently over. Note that this could be a control on a program window. 
Dim mousepos As POINT TYPE ' coordinates of the mouse cursor 

Dim wintext As String, slength As Long ' receive title bar text and its length 
Dim hwnd As Long ' handle to the window found at the point 

Dim retval As Long ' return value 





" Determine the window the mouse cursor is over. 

















retval = GetCursorPos (mousepos) " get the location of the mouse 
hwnd = WindowFromPoint (mousepos.x, mousepos.y) ' determine the window that's there 
If hwnd = 0 Then ' error or no window at that point 
Debug.Print "No window exists at that location." 
End 
End If 








' Display that window's title bar text 











slength = GetWindowTextLength (hwnd) " get length of title bar text 

wintext = Space(slength + 1) ' make room in the buffer to receive the string 
slength = GetWindowText (hwnd, wintext, slength + 1) " get the text 

wintext = Left (wintext, slength) ' extract the returned string from the buffer 





Debug.Print "Title bar text of the window: "; wintext 


Category: Windows 
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Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/windowfrompoint.html 
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WinHelp Function 


Declare Function WinHelp Lib "user32.d1l1" Alias "WinHelpA" (ByVal hWndMain 
As Long, ByVal lpHelpFile As String, ByVal uCommand As Long, dwData As Any) 
As Long 


Platforms 


e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 
e Windows 2000: Supported. 

e Windows CE: Not Supported. 


Description & Usage 


WinHelp opens a Windows Help file or somehow manipulates an open Help file. The precise action taken by the 
function depends on the value passed as uCommand, but all of them work with Windows Help files. This 
function is used to provide all access points between an application and its help file(s). 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


Whenever passing a String or a Long (not including an array of Longs) as dwData, you must preceed it with the 
ByVal keyword. Do not use the keyword when passing any data structure or an array. 


Parameters 


hWndMain 
In most cases, a handle to the window which is opening the Help file. If «Command is either 


HELP_CONTEXTMENU or HELP_WM_HELP, this is a handle to the particular control to open up 
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context-sensitive Help about. 
IpszHelp 
The filename of the Help file to display. The filename can be followed by the > character and the name of 
a secondary Help window (defined in the Help file) to open instead of the primary one. 
uCommand 
Exactly one of the following flags specifying which action the function is to take on the Help file: 
HELP_COMMAND 
Execute a Help macro or macro string. dwData is a string specifying the name(s) of the Help 
macro(s) to run. If more than one is specified, separate each name with semicolons. 
HELP_CONTENTS 
Display the Contents topic of the Help file. dwData must be 0. This flag is obsolete; use the 
HELP_FINDER flag instead. 
HELP_CONTEXT 
Display the topic identified by the value passed as dwData. 
HELP_CONTEXTMENU 
Display the Help topic associated with the window's selected control in a pop-up window. dwData 
is an array of pairs of Longs (dwords): the first in a pair is a control identifier, and the second in a 
pair is the context identifier of the associated Help topic. The array's last pair must be two zeros. 
HELP_CONTEXTPOPUP 
Display the topic identified by the value passed as dwData in a pop-up window. 
HELP_FINDER 
Display the Help Topics dialog box. dwData must be 0. 
HELP_FORCEFILE 
Ensure that Windows Help is displaying the correct Help file; if it is not, then display the correct 
one instead. dwData must be 0. 
HELP_HELPONHELP 
Display the Help on using Windows Help Help file, which is part of Windows. dwData must be 0. 
HELP_INDEX 
Same as HELP_CONTENTS. 
HELP_KEY 
Display the topic in the keyword table that matches the keyword(s) in the string passed as dwData. 
If multiple matches are found, display the Index topic with each found topic in the Topics Found 
dialog box. Multiple keywords in dwData must be separated by semicolons. 
HELP_MULTIKEY 
Display the topic specified by a keyword in an alternative keyword table. dwData is a 
MULTIKEYHELP structure which specifies a table footnote character and a keyword. 
HELP_PARTIALKEY 
Same as HELP_KEY, except that to display the index without passing a keyword, pass an empty 
string as dwData. 
HELP_QUIT 
Close Windows Help unless other programs currently need it. 
HELP_SETCONTENTS 
Set which Help topic is considered to be the Contents topic. dwData is the context identifer of the 
topic to set as the Contents. 
HELP_SETINDEX 
Same as HELP_SETCONTENTS. 
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HELP_SETPOPUP_POS 
Set the position of a subsequent pop-up window. dwData is a POINT_TYPE structure identifying 
the coordinates of the upper-left corner of the subsequent pop-up window. 
HELP_SETWINPOS 
Display the Help window, if it is minimized or hidden, and set its size and position. dwData is a 
HELPWININFO structure holding the size and position information of the desired Help window. 
HELP_TCARD 
Indicate that the topic to display is for a training card. This must be combined with another flag. 
HELP_WM_HELP 
Display the topic for the control identified by hWndMain. dwData is an array of pairs of Longs 
(dwords): the first in a pair is a control identifier, and the second in a pair is the context identifier 
of the associated Help topic. The array's last pair must be two zeros. 
dwData 
Depends on the value of uCommand. 


Constant Definitions 



































Const HELP_COMMAND = &H102 
Const HELP CONTENTS = &H3 
Const HELP CONTEXT = &H1 
Const HELP _CONTEXTMENU = &HA 
Const HELP_CONTEXTPOPUP = &H8 
Const HELP_FINDER = &HB 
Const HELP_FORCEFILE = &H9 
Const HELP _HELPONHELP = &H4 
Const HELP_INDEX = &H3 

Const HELP_KEY = &H101 

Const HELP_MULTIKEY = &H201 
Const HELP _PARTIALKEY = &H105 
Const HELP_QUIT = &H2 

Const HELP_SETCONTENTS = &H5 
Const HELP_SETINDEX = &H5 
Const HELP _SETPOPUP_POS = &HD 
Const HELP_SETWINPOS = &H203 
Const HELP_TCARD = &H8000 
Const HELP_WM_HELP = &HC 
Example 


' This code is licensed according to the terms and conditions listed here. 


' Display the Help Topics dialog box of the Help file C:\MyApp\appehelp.hlp. 
The window Forml is opening Windows Help. 
Dim retval As Long ' return value 


' 
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' Display the Help file as mentioned above. Note how the ByVal keyword must 
' be used because we're passing a regular Long to it. 
retval = WinHelp (Forml.hWnd, "C:\MyApp\apphelp.hlp", HELP_FINDER, ByVal 0) 


Category 
Help 


Go back to the alphabetical Function listing. 


Go back to the Reference section index. 





Last Modified: August 13, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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WriteFile Function 


Declare Function WriteFile Lib "kernel32.d11" (ByVal hFile As Long, 
lpBuffer As Any, ByVal nNumberOfBytesToWrite As Long, 
lpNumberOfBytesWritten As Long, lpOverlapped As Any) As Long 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WriteFile writes a series of bytes (originally stored in any variable, array, or structure) to a file. The file must 
of course have been opened with at least write-level access. If the file is synchronous (not overlapped), the 
function begins writing to the file at the current position of the file pointer, and the function automatically 
adjusts the file pointer to point to the byte immediately after the last byte written. If the file is asynchronous 
(overlapped), the structure passed as lpOverlapped identifies the point to begin writing at, and the program 
calling the function is responsible for updating the file pointer. 


Return Value 


If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function 
returns a non-zero value. 


Visual Basic-Specific Issues 


When passing a string as lpBuffer, the ByVal keyword must preceed the string. The keyword is not necessary 
for any other data types passed for lpBuffer. When passing 0 for JpOverlapped, the expression ByVal CLng(0) 
must be used. 
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Parameters 


hFile 
The handle to the file to write to. The file must have at least write-level access. 
lpBuffer 
The variable, array, or string holding the data to write to the file. 
nNumberOfBytesTo Write 
The number of bytes of data to write to the file. 
lpNumberOfBytes Written 
Receives the number of bytes of data actually written to the file. 
lpOverlapped 
If the file is asynchronous (overlapped), this is an OVERLAPPED structure specifying where to begin 
writing at. If the file is synchronous (not overlapped), this must be 0. 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Write both a Long (32-bit) number and a String to the file 

' C:\Test\myfile.txt. Notice how the ByVal keyword must be used 

' when writing a string variable. 

Dim longbuffer As Long ' long to write to the file 

Dim stringbuffer As String ' string to write to the file 

Dim numwritten As Long ' receives number of bytes written to the file 
Dim hFile As Long ' handle of the open file 

Dim retval As Long ' return value 


' Open or create the file being written to. 
hFile = CreateFile("C:\Test\myfile.txt", GENERAL WRITE, FILE_SHARE_ READ, 0, 
CREATE ALWAYS, FILE ATTRIBUTE ARCHIVE, 0) 





If hFile = -1 Then ' the file could not be opened 
Debug.Print "Unable to open the file -- it probably does not exist." 
End ' abort the program 

End If 


' Write a Long-type number (27) to the file 
longbuffer = 27 ' the Long value to write to the file 
retval = WriteFile(hFile, longbuffer, Len(longbuffer), numwritten, CLng(0) ) 


' Write a 10-character string to the file 
stringbuffer = "Anonymous!" ' the String to write to the file 
retval = WriteFile(hFile, ByVal stringbuffer, 10, numwritten, CLng(0) ) 





" Close the file. 
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retval = CloseHandle (hFile) 





See Also 


ReadFile, SetFilePointer 


Category 


Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 


Last Modified: October 13, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/writefile.html 
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WritePrivateProfileString Function 











Declare Function WritePrivateProfileString Lib "kernel32.d1l1" Alias 
"WritePrivateProfileStringA" (ByVal lpApplicationName As String, ByVal lpKeyName As 
String, ByVal lpString As String, ByVal lpFileName As String) As Long 


























Platforms: Win 32s, Win 95/98, Win NT 


WritePrivateProfileString sets a value inside of an INI file. This function can also be used to set numerical values if they are 
in string form, for example using "1" to represent the number 1. If the INI file you try to write to does not exist, it will be 
created. Likewise, if the section or value does not exist, it will also be created. The function returns 0 if an error occurs, or 1 if 
successful. Note that INI file support is only provided in Windows for backwards compatibility; using the registry to store 
information is preferred. 


lpApplicationName 

The section of the INI file to write to. 
lpKeyName 

The name of the value to set. 
lpString 

The string to set as the value. 
IpFileName 

The filename of the INI file to write to. 


























Example: 

' Set the "username" setting in the [Default] section of 

' C:\MyProgram\config.ini to "Rimmer". Also set the "useinfo" setting under the sam 
" section to 1 (i.e., "1"). 

Dim retval As Long ' return value 





' Set the string value. 
retval = WritePrivateProfileString("Default", "username", "Rimmer", 
"C:\MyPrograms\config.ini") 











' Set the numeric value. 
retval = WritePrivateProfileString("Default", "useinfo", "1", 
"C:\MyPrograms\config.ini") 





See Also: GetPrivateProfileString, WriteProfileString 
Category: INI Files 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/w/writeprivateprofilestring.html 
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WriteProfileString Function 


Declare Function WriteProfileString Lib "kernel32.d1l1" Alias 
"WriteProfileStringA" (ByVal lpszSection As String, ByVal lpszKeyName As String, 
ByVal lpszString As String) As Long 








Platforms: Win 32s, Win 95/98, Win NT 


WriteProfileString sets a value inside of the WIN.INI file. This function can also be used to set numerical values if they 
are in string form, for example using "1" to represent the number 1. If the section or value does not exist, it will be 
created. Note that, since Windows normally handles the WIN.INI file by iself, extreme care should be taken when 
writing directly to it. This function if basically a watered-down version of WritePrivateProfileS tring because, unlike this 
function, it works with any INI file. The function returns 0 if an error occurs, or a non-zero value if successful. Note that 
INI file support is only provided in Windows for backwards compatibility; using the registry to store information is 
preferred. 


IpszSection 

The section of WIN.INI to write to. 
lpszKeyName 

The name of the value to set. 
IpszString 

The string to set as the value. 


Example: 


' Set the "Wallpaper" setting in the [Desktop] section of WIN.INI 
" to C:\Windows\Clouds.bmp. 
' WARNING: Use extreme caution when editing the WIN.INI file, because writing bad 
data to 

' it could have unpredictable and disasterous results to the system! 

Dim retval As Long ' return value 








' Set the value. 
retval = WriteProfileString("Desktop", "Wallpaper", "C:\Windows\Clouds.bmp") 


See Also: GetProfileString, WritePrivateProfileString 
Category: INI Files 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 





Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/w/writeprofilestring.html 
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WSACleanup Function 

Declare Function WSACleanup Lib "wsock32.d1l" () As Long 
Platforms 

e Windows 95: Supported. 

e Windows 98: Supported. 

e Windows NT: Requires Windows NT 3.1 or later. 

e Windows 2000: Supported. 

e Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WSACleanup frees the resources allocated when when the program began using Windows Sockets (Winsock) functions. 
Your program must call this function once it no longer needs to use Winsock functions, so that it frees the resources the prior 
call to WSAStartup consumed. The resources will not be freed unless the program calls WSACleanup the same number of 
times as it called WSAStartup (in case that function had been called more than once). 


Return Value 


If successful, the function returns zero. If an error occured, the function returns -1 (use WSAGetLastError to get the error 
code). 





Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


Print the IP address associated with a domain name specified by the user. Winsock is briefly used to resolve the domain name 
and format a printable IP address string. The user enters the domain name to resolve in text box txtDomain, and the domain 
name is resolved when the user clicks button cmdGetIP. 
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To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dll" (ByVal wVersionRegquested As 
Integer, lpWSAData _ 
As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 
Public Const AF_INET = 2 
Public Declare Function gethostbyname Lib "wsock32.d1l1l" (ByVal name As String) As 
Long 












































Public Declare Function inet _ntoa Lib "wsock32.d1ll1" (ByVal inaddr As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d1l1" Alias "RtlMoveMemory" (Destination 


As Any, Source _ 
As Any, ByVal length As Long) 
Public Declare Function lIstrlen Lib "kernel32.dl1" Alias ' 











lstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias 






































lstrcpyA" (ByVal lpStringl 











As Any, ByVal _ 
lpString2 As Any) As Long 





' Define a relevant API macro. 





Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 





2)) 
End Function 


' *** Place the following code inside the form window. *** 


Private Sub cmdGetIP_Click () 
Dim sockinfo As WSADATA ' information about Winsock 
Dim hostinfo As HOSTENT ' information about an Internet host 
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Dim pHostinfo As Long ' pointer to a HOSTENT structure 

Dim plPAddress As Long ' pointer to an IP address dword 

Dim ipAddress As Long ' an IP address, packed into a dword 

Dim plIPString As Long ' pointer to an IP address formatted as a string 
Dim ipString As String ' holds a human-readable IP address string 

Dim retval As Long ' generic return value 








' Open up a Winsock session, using version 2.2. 


retval = WSAStartup (MAKEWORD (2, 2), sockinfo) 
If retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 











Exit Sub 
End If 


Get information about the domain specified in txtDomain. 
pHostinfo = gethostbyname (txtDomain. Text) 

If pHostinfo = 0 Then 

Debug.Print "Unable to resolve domain name." 








Else 

' Copy the data into a HOSTENT structure. 

CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "A non-IP address was returned." 








Else 


Copy the pointer to the first (and probably only) IP 





address in the structure. 
CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 
' Copy the actual IP address. 
CopyMemory ipAddress, ByVal plIPAddress, 4 
" Convert the IP address into a human-readable string. 
piPString = inet ntoa(ipAddress) 





Copy the result into a string variable. 
ipString = Space(lstrlen(pIPString) ) 





retval = lstrcpy(ipString, pIPString) 
' Print the result: a human-readable IP address. 
Debug.Print ipString 











End If 
End If 


Close the Winsock session. 
retval = WSACleanup () 
End Sub 


See Also 


WSAStartup 


Category 
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Winsock 


Back to the Function list. 
Back to the Reference section. 


Last Modified: October 29, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/wsacleanup.html 
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WSAGetLastError Function 


Declare Function WSAGetLastError Lib "wsock32.d1l1" () As Long 








Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WSAGetLastError identifies the last error code reported by the last Windows Sockets (Winsock) function call. Note that 
successful Winsock functions typically do not clear this error code, so WSAGetLastError will identify the last error that 
occured. Since most Winsock functions only return whether or not they failed, this function should be used to get a better 
description of the exact error that occured. 


Return Value 


The function returns one of the Winsock error codes identifying the last Winsock error that occured. 





Visual Basic-Specific Issues 


None. 


Parameters 


None. 


Example 


Intentionally cause an error by failing to initialize Winsock before calling its functions. This is the same code that is in the 
WSAStartup page's example, except that the call to WSAStartup has been removed. This code intentionally does not work. 
Any Winsock errors that occur should be reported via WSAGetLastError. 


To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window. 
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This code is licensed according to the tern 





' (declarations) section o 


(Copy them to the 











Declarations and such needed for the exampl 


H= 


ns and conditions listed here. 


e: 
a module.) 





Public Declare Function WSAGetLastError Lib "wsock32.d11" () As Long 
Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 
Public Type HOSTENT 


h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 
Public Const AF_INET 
Publ Declare 


2 
lic 





Long 
Public 
Publ 


Declare Function inet ntoa Lib 











lic Declare 


Function gethostbyname Lib "wsock32.d11" 


"wsock32.d11" 
Sub CopyMemory Lib "kernel32.dl11" Alias 


(ByVal name As String) As 


(ByVal 
"Rt lMoveMemory" 


inaddr As Long) 
( 


As Long 








Destination 





Source _ 
As Any, ByVal length As Long) 
Decl lstrien Lib "kernel 


As Any, 


Public 


lias "lstrlenA" (ByVal lpString 











lare Function 
As 


Long 
Declare Function lstrcpy 


As Any) 
Publ 




















Lic Lib "kernel 




















lias "lstrcpyA" (ByVal lpStringl 











As Any, ByVal _ 


lpString2 As Any) As Long 


Defin useful API macros. 








som 





Public Function MAKEWORD (ByVal bLow As Byte, 
MAKEWORD Val("&H" & Right ("00" 


2)) 
End Function 





Public Function LOBYTE (ByVal 
LOBYTE Val("&H" & Right ("00" 
End Function 


& Hex 


Public Function HIBYTE (ByVal 
HIBYTE Val ("&H" 
End Function 





T £ 








In the event of an error, 
' window. Ideall 
' manner in a real program (e.g., 
' is just an example. 


Public Sub ReportWinsockError () 


Dim winsockError As Long ' 





winsockError 
Debug.Print 


WSAGet LastError () 
"Winsock error"; 





& Hex (bHigh), 


wValue As Integer) 


wValue As Integer) 


& Left (Right ("0000' 


print the Winsock error number in the 


winsockError; 


ByVal bHigh As Byte) As Integer 
2) & Right ("00" & Hex(bLow), 


As Byte 


(wValue), 2)) 


As Byte 
& Hex(wValue), 


í 4), 2)) 





Debug 


Ly the error code would be used in a more meaningful 
printing out a textual error message), 


but this 


the Winsock error code 


"reported!" 





End Sub 
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' *** Place the following code inside the form window. *** 


Private Sub cmdGetIP_Click () 


























Dim sockinfo As WSADATA ' information about Winsock 

Dim hostinfo As HOSTENT ' information about an Internet host 

Dim pHostinfo As Long ' pointer to a HOSTENT structure 

Dim plIPAddress As Long ' pointer to an IP address dword 

Dim ipAddress As Long ' an IP address, packed into a dword 

Dim plIPString As Long ' pointer to an IP address formatted as a string 
Dim ipString As String ' holds a human-readable IP address string 

Dim retval As Long ' generic return value 





Get information about the domain specified in txtDomain. 


pHostinfo = gethostbyname (txtDomain. Text) 





If pHostinfo = 


0 Then 


Debug.Print "Unable to resolve domain name." 
ReportWinsockError 


Else 


' Copy the data into a HOSTENT structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 


Else 





Debug.Print "A non-IP address was returned." 
ReportWinsockError 


' Copy the pointer to the first (and probably only) IP 





address in the structure. 


End If 
End If 


CopyMemory plIPAddress, ByVal hostinfo.h_addr_list, 4 
' Copy the actual IP address. 
CopyMemory ipAddress, ByVal plIPAddress, 4 





Convert the IP address into a human-readable string. 
piPString = inet ntoa(ipAddress) 
' 


Copy the result into a string variable. 
ipString = Space(lstrilen(pIPString) ) 





retval = lstrcpy(ipString, pIPString) 
' Print the result: a human-readable IP address. 
Debug.Print ipString 








Close the Winsock session. 


retval = WSACleanup() 


End Sub 


Category 
Winsock 


Back to the Function list. 
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Back to the Reference section. 





Last Modified: October 29, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/w/wsagetlasterror.html 
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WSAStartup Function 


Declare Function WSAStartup Lib "wsock32.dll1" (ByVal wVersionRequested As Integer, 
lpWSAData As WSADATA) As Long 














Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WSAStartup initializes the use of Windows Sockets (Winsock) for the calling program. This function must be called before 
any other Winsock functions are called, in order to perform any necessary initialization. The program can specify which 
version of Winsock it wants to use. When your program no longer needs to call Winsock function, it must call WSACleanup 
to free resources. 


Return Value 


If successful, the function returns zero. If an error occured, the function returns one of the following one of the following 
values specifying the error: 


WSAEFAULT 

A valid WSADATA structure was not passed for JpWSAData. 
WSAEINPROGRESS 

A Winsock 1.1 blocking operation is in progress. 
WSAEPROCLIM 

The limit of the number of tasks supported by the Winsock implementation has been reached. 
WSASYSNOTREADY 

The network subsystem is not ready for network communication. 
WSAVERNOTSUPPORTED 

The requested version of Winsock is not provided by the current Winsock implementation 


Visual Basic-Specific Issues 


None. 
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Parameters 


wVersionRequested 
The highest version of Winsock your program can use. If you wish, your program could specify a lower version than 
2.2. The low-order byte contains the major version number, and the high-order byte contains the minor version 
number. In other words, &H202 means Winsock 2.2 and &H2 means Winsock 2.0. 

IpWSAData 
Receives information about the current Winsock implementation. 


Constant Definitions 


Const WSAEFAULT = 10014 











Const WSAEINPROGRESS = 10036 
Const WSAEKPROCLIM = 10067 











Const WSASYSNOTREADY = 10091 
Const WSAVERNOTSUPPORTED = 10092 











Example 


Print the IP address associated with a domain name specified by the user. Winsock is briefly used to resolve the domain name 
and format a printable IP address string. The user enters the domain name to resolve in text box txtDomain, and the domain 
name is resolved when the user clicks button cmdGetIP. 


To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window. 


This code is licensed according to the terms and conditions listed here. 
' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dl1" (ByVal wVersionRequested As 
Integer, lpWSAData _ 
As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d11" () As Long 
Public Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
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End Type 

Public Const AF_INET = 2 

Public Declare Function gethostbyname Lib "wsock32.d1l1" (ByVal name As String) As 
Long 























Public Declare Function inet ntoa Lib "wsock32.d11" (ByVal inaddr As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 


As Any, Source _ 











As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "IlstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 















































As Any, ByVal _ 
lpString2 As Any) As Long 





' Define some useful API macros. 





Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 


MAKEWORD = Val("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 
2)) 


End Function 





Public Function LOBYTE(ByVal wValue As Integer) As Byte 


LOBYTE = Val("&H" & Right ("00" & Hex(wValue), 2)) 
End Function 


Public Function HIBYTE(ByVal wValue As Integer) As Byte 


HIBYTE = Val("&H" & Left (Right ("O000" & Hex(wValue), 4), 2)) 
End Function 





' *** Place the following code inside the form window. *** 


Private Sub cmdGetIP_Click () 























Dim sockinfo As WSADATA ' information about Winsock 

Dim hostinfo As HOSTENT ' information about an Internet host 

Dim pHostinfo As Long ' pointer to a HOSTENT structure 

Dim plPAddress As Long ' pointer to an IP address dword 

Dim ipAddress As Long ' an IP address, packed into a dword 

Dim plIPString As Long ' pointer to an IP address formatted as a string 
Dim ipString As String ' holds a human-readable IP address string 

Dim retval As Long ' generic return value 








' Open up a Winsock session, using version 2.2. 


retval = WSAStartup (MAKEWORD (2, 2), sockinfo) 

If retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 








End If 








Display the version of Winsock being used, and the description 
provided by the implementation (after removing the empty space). 
Debug.Print "Using Winsock version"; LOBYTE(sockinfo.wVersion); "."; 


A 
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HIBYTE (sockinfo.wVersion) 
Debug.Print "Description: "; Left (sockinfo.szDescription, 
InStr(sockinfo.szDescription, vbNullChar) = 1) 














' Get information about the domain specified in txtDomain. 
pHostinfo = gethostbyname (txtDomain. Text) 
If pHostinfo = 0 Then 

Debug.Print "Unable to resolve domain name." 








Else 
' Copy the data into a HOSTENT structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 
Debug.Print "A non-IP address was returned." 





Else 
' Copy the pointer to the first (and probably only) IP 
address in the structure. 
CopyMemory plPAddress, ByVal hostinfo.h_addr_list, 4 








' Copy the actual IP address. 
CopyMemory ipAddress, ByVal plIPAddress, 4 





" Convert the IP address into a human-readable string. 
piPString = inet ntoa(ipAddress) 

' Copy the result into a string variable. 

ipString = Space(lstrilen(pIPString) ) 





retval = lstrcpy(ipString, pIPString) 





' Print the result: a human-readable IP address. 
Debug.Print ipString 





End If 
End If 


' Close the Winsock session. 
retval = WSACleanup () 
End Sub 


See Also 
WSACleanup 


Category 


Winsock 


Back to the Function list. 
Back to the Reference section. 








Last Modified: October 29, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/w/wsastartup.html 
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ZeroMemory Function 


Declare Sub ZeroMemory Lib "kernel32.d1l1" Alias "RtlZeroMemory" (Destination As 
Any, ByVal Length As Long) 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


ZeroMemory fills a location in memory with zeros. The function sets each byte starting at the given memory location 
to zero. The memory location is identified by a pointer to the memory address. 


Return Value 


ZeroMemory does not return a value. 


Visual Basic-Specific Issues 


A pointer to any variable can be automatically generated merely by passing that variable as Destination. However, if 
either a String or a Long holding the desired memory address is passed, the ByVal keyword must preceed it. 


Parameters 


Destination 


A pointer to the location in memory (often the memory address of a variable) to begin filling with zeros. 
Length 


The number of memory bytes, beginning with the address identified by Destination, to set to zeros. 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Initialize all the elements in an array to the value 0. 
Dim bytearray(0 To 9) as Byte ' array of 10 bytes 
Dim c As Integer ' counter variable 


' Fill the memory at bytearray() with zeros. Note that, to identify the pointer 


' to bytearray()'s memory location, it is passed as normal. 
ZeroMemory bytearray(0), 10 ' zero out 10 bytes 
' Display the results to verify that it worked. 
For c = 0 To 9 ' loop through each element 
Debug.Print bytearray(c); ' each value displayed will be 0 
Next c 
See Also 
FillMemory 


Category 


Memory 


Go back to the alphabetical Function listing. 
Go back to the Reference section index. 





Last Modified: July 26, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/z/zeromemory.html 
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Windows API Reference: Functions 


Last Update: January 21, 2001 
Number of Functions Listed: 357 (4 added) 


Below is a categorical list of the API functions currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to: 


e Accessibility 

e Audio 

e Bitmaps 

e Brushes 

e Common Controls 
e Common Dialog 
e Cursor 

e Devices 

e Dialog Boxes 

e Errors 

e Files 

e Filled Shapes 

e Fonts & Text 

e Handles 

e Help 

e Icons 

e INI Files 

e Input (General) 
e Joysticks 


e Keyboard 
e Lines & Curves 
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e Math 

e Media Control Interface (MCI) 
e Memory 

e Menus 


e Messages 
e Mouse 


e National Language Support 
e OLE 

e Painting & Drawing 

e Pens 

e Printers 

e Processes & Threads 


e Rectangles 

e Regions 

e Registry 

e Shell 

e Shutdown 

e Strings 

e Synchronization 

e System Information 
e Time 

e Timers 

e Tool Help 

e Window Classes 

e Window Procedures 
e Window Properties 
e Windows 

e Winsock 

e Other 


e Accessibility 
o GetSystemMetrics 


o SystemParametersInfo 
e Audio 

o auxGetDevCaps 

o auxGetNumDevs 


o auxGetVolume 
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o auxSetVolume 


o PlaySound 
o sndPlaySound 


o waveOutGetDevCaps 
o waveOutGetNumDevs 


o waveOutGetVolume 

o waveOutSetVolume 
e Bitmaps 

o BitBit 

o ExtFloodFill 

o GetPixel 

o SetPixel 

o SetPixelV 

o StretchBlt 
e Brushes 

o CreateHatchBrush 


o CreateSolidBrush 


o GetBrushOrgEx 

o SetBrushOrgEx 
e Common Controls 

o InitCommonControlsEx 
e Common Dialog 

o ChooseColor 

o ChooseFont 


o CommD]I]gExtendedError 
o GetOpenFileName 
o GetSaveFileName 
o PrintDlg 
e Cursor 
o ClipCursor 
o CreateCursor 
o DestroyCursor 


o GetClipCursor 
o GetCursor 


o GetCursorPos 

o LoadCursor 

o LoadCursorFromFile 
o SetCursor 

o SetCursorPos 
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O 


O 


SetSystemCursor 
ShowCursor 


e Devices 


ChangeDisplaySettings NEW 
CreateDC 


DeleteDC 
DeleteObject 


EnumDisplaySettings NEW 
GetDC 


GetStockObject 
ReleaseDC 


SelectObject 


e Dialog Boxes 


O 


O 


O 


MessageBox 
MessageBoxEx 
MessageBoxlIndirect 


e Errors 


Beep 
GetLastError 


MessageBeep 
SetLastError 
SetLastErrorEx 


CopyFile 
CreateDirectory 


CreateDirectoryEx 
CreateFile 


DeleteFile 
FindClose 
FindFirstFile 
FindNextFile 


GetDiskFreeSpace 
GetDiskFreeSpaceEx 
GetDriveType 
GetFileAttributes 
GetFileInformationB yHandle 
GetFileSize 

GetFileTime 

GetFile VersionInfo 
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o GetFile VersionInfoSize 
o GetFullPathName 


o GetLogicalDrives 
o GetLogicalDriveStrings 
o GetShortPathName 
o GetTempFileName 
o MoveFile 
o ReadFile 
o RemoveDirectory 
o SetFileAttributes 
o SetFilePointer 
o SetFileTime 
o VerQuery Value 
o WriteFile 

e File System 
o GetVolumeInformation 
o SetVolumeLabel 

e Filled Shapes 
o Chord 
o Ellipse 
o FillRect 
o FrameRect 
o InvertRect 


o Pie 
o Polygon 


o PolyPolygon 


o Rectangle 
o RoundRect 


e Fonts & Text 
o CreateFont 
o CreateFontIndirect 
o EnumFontFamilies 
o EnumFontFamiliesEx 


o GetTextAlign 


o SetTextAlign 
o TextOut 
e Handles 
o CloseHandle 
e Help 
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o WinHelp 
e Icons 


o DestroylIcon 
o Drawlcon 


o DrawlconEx 
o ExtractIcon 
o ExtractIconEx 
e INI Files 
o GetPrivateProfileInt 


o GetPrivateProfileString 
o GetProfileInt 

o GetProfileString 

o WritePrivateProfileS tring 


o WriteProfileString 
e Input (General) 


o SendInput 

e Joysticks 
o joyGetDevCaps 
o joyGetNumDevs 
o joyGetPos 

e Keyboard 
o GetAsyncKeyState 
o GetKeyboardState 
o GetKeyState 
o keybd_event 


o SetKeyboardState 
e Lines & Curves 


o AngleArc 

o Are 

o ArcTo 

o GetArcDirection 
o LineTo 

o MoveToEx 

o PolyBezier 

o PolyBezierTo 

o Polyline 

o PolylineTo 


o PolyPolyline 
o SetArcDirection 
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e Math 
o MulDiv 

e Media Control Interface (MCI) 
o mceiGetErrorStrin 
o mciSendStrin 


e Memory 
o CopyMemory 


o FillMemory 
o GlobalAlloc 


o GlobalFree 
o GlobalLock 


o GlobalMemoryStatus 

o GlobalMemoryStatusEx 
o GlobalUnlock 

o MoveMemory 


o ZeroMemory 
e Menus 


o CreatePopupMenu 


o DestroyMenu 
o GetMenu 


o GetMenultemCount 
o GetMenultemInfo 
o GetSystemMenu 

o InsertMenultem 

o RemoveMenu 

o SetMenultemInfo 


o TrackPopupMenu 


o TrackPopupMenuEx 
e Messages 


o SendMessage 
e Mouse 


o GetCapture 
o GetDoubleClickTime 


o mouse event 
o ReleaseCapture 


o SetCapture 
o SetDoubleClickTime 


o SwapMouseButton 
e National Language Support 
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o GetCurrencyFormat 
o GetDateFormat 


o GetNumberFormat 
o GetThreadLocale 
o GetTimeFormat 
o SetThreadLocale 
e OLE 
o CoTaskMemFree 
Painting & Drawing 
o GetWindowRen 
o SetWindowRgn 
e Pens 
o CreatePen 
o CreatePenIndirect 
e Printers 
o ClosePrinter 
o EndDoc 


o EndPage 
o EnumJobs 


o EnumPrinters 
o OpenPrinter 
o PrinterProperties NEW 
o StartDoc 
o StartPage 
e Processes & Threads 
o GetEnvironmentVariable 
o SetEnvironmentVariable 
e Rectangles 
o CopyRect 


o EqualRect 
o InflateRect 


o IntersectRect 

o IsRectEmpty 

o OffsetRect 

o PtInRect 

o SetRect 

o SetRectEmpty 
o SubtractRect 

o UnionRect 
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e Regions 
o CombineRgn 
o CreateEllipticRgn 
o CreateEllipticRgnIndirect 
o CreatePolygonRgn 
o CreatePolyPolygonRgn 
o CreateRectRgn 
o CreateRectRgnIndirect 
o CreateRoundRectRgn 
o EqualRgn 
o FillRgn 
o FrameRgn 
o GetPolyFillMode 
o GetRgnBox 
o InvertRgn 
o OffsetRgn 
o PtInRegion 
o RectInRegion 
o SetPolyFillMode 
e Registry 
o RegCloseKey 
o RegCreateKeyEx 
o RegDeleteKey 
o RegDelete Value 
o RegEnumKeyEx 
o RegEnumValue 
o RegOpenKeyEx 
o RegQueryValueEx 
o RegSetValueEx 


o ExitWindowsDialog 
o PickIconDlg 


o RestartDialog 
o SHAddToRecentDocs 


o SHBrowseForFolder 


o Shell NotifyIcon 
o ShellExecute 


o ShellExecuteEx 
o SHEmptyRecycleBin 
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o SHFileOperation 


o SHFreeNameMappings 
o SHGetFileInfo 


o SHGetFolderLocation 
o SHGetFolderPath 
o SHGetPathFromIDList 


o SHGetSpecialFolderLocation 
o SHGetSpecialFolderPath 
o SHQueryRecycleBin 


o SHUpdateRecycleBinIcon 
e Shutdown 
o LockWorkStation 


e Strings 
o CharLower 
o CharUpper 
o CompareString 
o Istrcmp 
o Istrcmpi 
o Istrcpy 


o Istrcepyn 
o Istrlen 


e Synchronization 
o WaitForSingleObject 
e System Information 
o GetComputerName 
o GetSysColor 
o GetSystemDirectory 


o GetTempPath 
o GetUserName 


o GetVersionEx 
o GetWindowsDirectory 
o SetSysColors 


o CompareFileTime 
o FileTimeToLocalFileTime 


o FileTimeToSystemTime 
o GetLocalTime 


o GetSystemTime 
o GetSystemTimeAsFileTime 
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o GetTickCount 
o GetTimeZonelInformation 
o LocalFileTimeToFileTime 
o SetSystemTime 
o SystemTimeToFileTime 
e Timers 
o KillTimer 
o QueryPerformanceCounter 
o QueryPerformanceFrequency 


o SetTimer 
e Tool Help 


o CreateToolhelp32Snapshot 
o Process32First 


o Process32Next 
e Window Classes 

o GetClassInfo 

o GetClassInfoEx 
o GetClassLong 

o GetClassName 
o GetWindowLong 
o RegisterClass 

o RegisterClassEx 
o SetClassLong 

o SetWindowLong 


o UnregisterClass 
e Window Procedures 
o CallWindowProc 


o DefWindowProc 
e Window Properties 
o EnumPropsEx 
o GetProp 
o RemoveProp 
o SetProp 
e Windows 
o BringWindowToTo 
o CreateWindowEx 
o DestroyWindow 
o EnableWindow 
o EnumChildWindows 
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o EnumThreadWindows 
o EnumWindows 

o FindWindow 

o FindWindowEx 

o FlashWindow 

o GetActiveWindow 


o GetDesktopWindow 
o GetFocus 


o GetForegroundWindow 
o GetParent 


o GetTopWindow 
o GetWindow 
o GetWindowRect 
o GetWindowText 
o GetWindowTextLength 
o GetWindowThreadProcessId 
o IsChild 
o IsIconic 
o IsWindow 
o IsWindowEnabled 
o IsZoomed 
o MoveWindow 
o SetActiveWindow 
o SetFocus 
o SetForegroundWindow 
o SetParent 
o SetWindowPos 
o SetWindowText 
o ShowWindow 
o WindowFromPoint 
e Winsock 
o closesocket 
o connect 


o gethostbyaddr 
o gethostbyname 


o gethostname 
o htonl 


o htons 
o inet_addr 
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o inet_nota 

o ioctlsocket NEW 
o recy 

o send 

o socket 


o WSACleanup 
o WSAGetLastError 


o WSAStartup 
e Other 
o ExitWindowsEx 


o Sleep 


Go back to the Reference section index. 


Last Modified: January 21, 2001 

This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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Windows API Reference: Structures 


Last Update: January 21, 2001 
Number of Structures Listed: 83 (0 added) 


Below is an alphabetical list of the API structures currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


o ACCESSTIMEOUT 
o ACL 

o ANIMATIONINFO 
o AUXCAPS 


o BROWSEINFO 
o BY_HANDLE_FILE INFORMATION 


o CHOOSECOLOR_TYPE 
o CHOOSEFONT_TYPE 
o CURRENCYFMT 


o DEVMODE 
o DEVNAMES 
o DOCINFO 


o ENUMLOGFONT 
o ENUMLOGFONTEX 
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e F 
o FILETIME 


o FILTERKEYS 
o FONTSIGNATURE 


o HARDWAREINPUT 
o HELPINFO 

o HELPWININFO 

o HIGHCONTRAST 
o HOSTENT 


o ICONMETRICS 

o INITCOMMONCONTROLSEX_TYPE 
o INPUT_TYPE 

o ITEMIDLIST 


o JOB_INFO_1 
o JOB_INFO_2 
o JOYCAPS 
o JOYINFO 


o KEYBDINPUT 


o LARGE_INTEGER 
o LOGFONT 
o LOGPEN 


o MEMORYSTATUS 

o MEMORYSTATUSEX 
o MENUITEMINFO 

o MINIMIZEDMETRICS 
o MOUSEINPUT 

o MOUSEKEYS 

o MSGBOXPARAMS 

o MULTIKEYHELP 


o NEWTEXTMETRIC 
o NEWTEXTMETRICEX 
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o NONCLIENTMETRICS 
o NOTIFYICONDATA 
o NUMBERFMT 


o OPENFILENAME 
o OSVERSIONINFO 
o OVERLAPPED 


o POINT_TYPE 

o PRINTDLG_TYPE 

o PRINTER DEFAULTS 
o PRINTER_INFO_1 

o PRINTER_INFO_2 

o PRINTER _INFO_4 

o PRINTER_INFO_5 

o PROCESSENTRY32 


5 O 


o RECT 


o SECURITY_ATTRIBUTES 
o SECURITY_DESCRIPTOR 
o SERIALKEYS 

o SHELLEXECUTEINFO 

o SHFILEINFO 

o SHFILEOPSTRUCT 

o SHITEMID 

o SHNAMEMAPPING 

o SHQUERYRBINFO 

o SOCKADDR 

o SOUNDSENTRY 

o STICKYKEYS 

o SYSTEMTIME 


o TEXTMETRIC 
o TIME_ZONE_INFORMATION 
o TOGGLEKEYS 
o TPMPARAMS 
e U 
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o ULARGE_INTEGER 


e V 
o VS_FIXEDFILEINFO 


o WAVEOUTCAPS 

o WIN32_FIND_ DATA 
o WNDCLASS 

o WNDCLASSEX 

o WSADATA 


Go back to the Reference section index. 


Last Modified: January 21, 2001 

This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
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ACCESSTIMEOUT Structure 


Type ACCESSTIMEOUT 
cbhSize As Long 
dwFlags As Long 
iTimeOutMSec As Long 

End Type 


ACCESSTIMEOUT-type variables specify information about the time-out feature of the Windows 
accessibility features. After the time-out period elapses (beginning with the last user input), the 
FilterKeys, HighContrast, MouseKeys, StickyKeys, and ToggleKeys accessibility features are disabled. 
The structure specifies settings for the time-out feature. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying the settings of the time-out feature: 
ATF_AVAILABLE = &H4 
The time-out period can be changed (this flag can be read but not set). 
ATF_ONOFFFEEDBACK = &H2 
Play a sound when the time-out period elapses and the accessibility features are 
deactivated. 
ATF_TIMEOUTON = &H1 
The time-out feature is activated. 
iTimeOutMSec 
The number of milliseconds after the last mouse or keyboard input to wait (the time-out period) 
before deactivating the accessibility features. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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ACL Structure 


Type ACL 
AclRevision As Byte 
Sbzl As Byte 
AclSize As Integer 
AceCount As Integer 
Sbz2 As Integer 

End Type 


ACL-type variables store information about an access-control list (ACL). The ACL structure is followed 
by zero or more access-control entries (ACEs) which the ACL is made up of. Note how the ACEs are not 
actually stored inside the ACL structure. 


AclRevision 

Must be set to the following flag which specifies the ACL's revision level: 

ACL_REVISION = 2 

The only valid revision level. 

Sbz1 

Reserved -- set to 0. This member merely aligns the structure's other members in memory. 
AclSize 

The combined size in bytes of this structure and all of the ACEs which follow it. 
AceCount 

The number of ACEs which follow this structure. 
Sbz2 

Reserved -- set to 0. This member merely aligns the structure's other members in memory. 


Used by: SECURITY_DESCRIPTOR 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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ANIMATIONINFO Structure 


Type ANIMATIONINFO 
cbhSize As Long 
iMinAnimate As Long 

End Type 


ANIMATIONINFO-type variables identify the settings of animation effects in Windows. The structure 
specifies whether Windows displays the animation when maximizing, restoring, or minimizing a 
window. 


cbSize 
The size in bytes of the structure. 

iMinAnimate 
If 0, then do not display the animations when maximizing, restoring, or minimizing a window. If 
non-zero, then display the animations. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
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AUXCAPS Structure 


Type AUXCAPS 
wMid As Integer 
wPid As Integer 
vDriverVersion As Long 
szPname As String * 32 
wlechnology As Integer 
wReservedl As Integer 
dwSupport As Long 

End Type 


Description & Usage 


The AUXCAPS structure stores information about an auxiliary audio device's capabilities. The structure 
also contains identifying information about the device, such as its version number. 


Visual Basic-Specific Issues 


None. 


Data Members 


wMid 
The manufacturer identifier of the device. 
wPid 
The product identifier of the device. 
vDriverVersion 
The version number of the device driver. The high-order byte contains the major version number, 
and the low-order byte contains the minor version number. 
szPname 
The name of the device, terminated by a null character. 
wTechnology 
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One of the following flags specifying which type of auxiliary audio device it is: 
AUXCAPS_AUXIN 

Line input audio device. 
AUXCAPS_CDAUDIO 

CD audio device. 
AUXCAPS_MASTER 

Master audio device. 
AUXCAPS_MIC 

Microphone audio device. 
AUXCAPS_MIDI 

MIDI audio device. 
AUXCAPS_PCSPEAKER 

PC speaker audio device. 
AUXCAPS_WAVE 

Waveform audio device. 


wReserved1 
Reserved -- set to 0. 

dwSupport 
A combination of zero or more of the following flags specifying various features which the device 
supports: 


AUXCAPS_LRVOLUME 

Supports separate left and right channel volume control. 
AUXCAPS_VOLUME 

Supports volume control. 


Constant Definitions 


Const AUXCAPS_AUXIN = &H2 
Const AUXCAPS _CDAUDIO = &H1 
Const Al 


A 
A 
AUXCAPS_ MASTER = &H8 
Const AUXCAPS_ MIC = &H4 

Const AUXCAPS_ MIDI = &H40 
Const AUXCAPS_PCSPEAKER = &H10 
Const AUXCAPS WAVE = &H20 
Const AUXCAPS_LRVOLUME = &H2 
Const AUXCAPS_ VOLUME = &H1 


Used By 








auxGetDevCaps 
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Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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BROWSEINFO Structure 


Type BROWSEINFO 
hwndOwner As Long 
pidlRoot As Long 
pszDisplayName As String 
lpszTitle As String 
ulFlags As Long 
lpfn As Long 
lParam As Long 
iImage As Long 

End Type 


Description & Usage 


The BROWSEINFO structure holds information used to create the Windows shell's Browse for Folder 
dialog box. This structure also receives some information regarding the user's final selection. 


Visual Basic-Specific Issues 


Because of a quirk in Visual Basic syntax, the AddressOf operator cannot be used directly to set the {pfn 
parameter to a pointer to a callback function. Since the AddressOf operator is only legal within a function 
call, a "dummy function" must be defined by the program which simply returns the value passed to it. 
See the example for SHBrowseForFolder to see how this can be done. 


Data Members 


hwndOwner 
A handle to the window opening the dialog box. 
pidlRoot 
A pointer to an ITEMIDLIST structure (a.k.a. a PIDL) which identifies the root folder for the 
dialog box. The user's selection is limited to this folder and any subfolders under it. 
pszDisplayName 
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Receives the null-terminated display name of the folder the user selects. This must be initialized 
to an empty string of at least 260 characters. 
IpszTitle 
The title of the dialog box, which will appear above the folder tree. 
ulFlags 
A combination of the following flags specifying additional options for the dialog box: 
BIF_BROWSEFORCOMPUTER 
Only allow the user to select a computer. 
BIF_BROWSEFORPRINTER 
Only allow the user to select a printer. 
BIF_BROWSEINCLUDEFILES 
With Internet Explorer 4.0 or later installed: Display files as well as folders in the tree. 
BIF_DONTGOBELOWDOMAIN 
Do not display network folders below the current domain level in the folder tree. 
BIF_EDITBOX 
With Internet Explorer 4.0 or later installed: Display an edit box above the folder tree 
allowing the user to directly enter the path of the folder to select. 
BIF_RETURNFSANCESTORS 
Only allow the user to select a file system ancestor. 
BIF_RETURNONLYFSDIRS 
Only allow the user to select a file system directory. 
BIF_STATUSTEXT 
Display an area for status text, which can be set by the callback function, above the folder 
tree. 
BIF_USENEWUI 
Windows 2000: Use the new user interface design of the dialog box. The new design 
includes a larger, resizable dialog box; drag and drop capability; reordering; context 
menus; and new folder creation, deletion, and other context menu commands. 
BIF_VALIDATE 
With Internet Explorer 4.0 or later installed: If the user types an invalid path into the 
edit box, send the BFFM_VALIDATEFAILED message to the callback function so it can 
alert the user. 
Ipfn 
A pointer to the BrowseCallbackProc callback function used to process the dialog box's messages. 
To use the default behavior, set this to 0. 
lParam 
An application-defined value to pass to the callback function, if needed. 
image 
Receives the index of the system image associated with the user's selection. 


Constant Definitions 
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Const BIF_BROWSEFORCOMPUTER = &H1000 
Const BIF_BROWSEFORPRINTER = &H2000 
Const BIF_BROWSEINCLUDEFILES = &H4000 
Const BIF_DONTGOBELOWDOMAIN = &H2 
Const BIF_EDITBOX = &H10 

Const BIF_RETURNFSANCESTORS = &H8 
Const BIF_RETURNONLYFSDIRS = &H1 
Const BIF_STATUSTEXT = &H4 

Const BIF_USENEWUI = &H40 

Const BIF_VALIDATE = &H20 


Used By 


SHBrowseForFolder 


Go back to the alphabetical Structure listing. 
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BY HANDLE FILE INFORMATION 
Structure 


Type BY_HANDLE_FILE_ INFORMATION 
dwFileAttributes As Long 
ftCreationTime As FILETIME 
ftLastAccessTime As FILETIME 
ftLastWriteTime As FILETIME 
dwVolumeSerialNumber As Long 
nFileSizeHigh As Long 
nFileSizeLow As Long 
nNumberOfLinks As Long 
nFileIndexHigh As Long 
nFileIndexLow As Long 

End Type 


BY_HANDLE_FILE_INFORMATION-type variables hold various pieces of information about a file. 
This information includes the file's attributes; its creation, last-access, and last-modified times and dates; 
the serial number of the disk the file is on; the file's size; the number of links to the file in the file system; 
and the unique file identifier value. Notice how the file size and file index, both being 64-bit values, are 
split into high-order and low-order halves of 32 bits each. To get the value they represent, you can 
append the hexadecimal or binary values of the two halves together. You can also use the formula 
actualvalue = high_order * 2432 + low_order to calculate it. 


dwFileAttributes 

One or more of the following flags which specify the file's various attributes: 
FILE_ATTRIBUTE_ARCHIVE = &H20 

An archive file (which most files are). 
FILE_ATTRIBUTE_COMPRESSED = &H800 

A file residing in a compressed drive or directory. 
FILE_ATTRIBUTE_DIRECTORY = &H10 

A directory instead of a file. 
FILE_ATTRIBUTE_HIDDEN = &H2 

A hidden file, not normally visible to the user. 
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FILE_ATTRIBUTE_NORMAL = &H80 
An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY = &H1 
A read-only file. 
FILE_ATTRIBUTE_SYSTEM = &H4 
A system file, used exclusively by the operating system. 
ftCreationTime 
The time and date of when the file was created. 
ftLastAccessTime 
The time and date of when the file was last accessed. 
ftLastWriteTime 
The time and date of when the file was last modified or written to. 
dwVolumeSerialNumber 
The serial number of the disk which the file is stored on. 
nFileSizeHigh 
The high-order half of the file's size. 
nFileSizeLow 
The low-order half of the file's size. 
nNumberOfLinks 
The number of links to the file in the file system. In NTFS (Win NT File System), this can be 
greater than one. In the FAT or FAT32 system (Win 32s, Win 95/98), this will always be 1. 
nFileIndexHigh 


The high-order half of a unique 64-bit identifier of the file. 
nFileIndexLow 


The low-order half of a unique 64-bit identifier of the file. 


Used by: GetFileInformationByHandle 


Go back to the alphabetical Structure listing. 
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CHOOSECOLOR_TYPE Structure 


Type CHOOSECOLOR_TYPE 
EStructsize As Long 
hwndOwner As Long 
hInstance As Long 
rgbResult As Long 
lpCustColors As Long 
Flags As Long 
lCustData As Long 
lpfnHook As Long 
lpTemplateName As String 

End Type 


Description & Usage 


The CHOOSECOLOR_TYPE structure stores the information passed to and from the Choose Color 
common dialog box. The structure's data members specify both the user's selection(s) as well as other 
information specifying how to create the Choose Color box. 


Visual Basic-Specific Issues 


Officially, this structure is called CHOOSECOLOR. However, that violates the case-sensitive name 
spacing of Visual Basic because Visual Basic cannot then distinguish it from the ChooseColor API 


function. The Windows API Guide calls this structure CHOOSECOLOR_TYPE to avoid the naming 
collision. 


Data Members 


[StructSize 
The size in bytes of the structure. 
hwndOwner 
A handle to the window opening the ChooseColor box, if any. 
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hInstance 
A handle to a dialog template to use in place of the default box. If this is not being used, set to 0. 
rgbResult 
Set to the RGB value of the default selected color before calling ChooseColor. The function 
places the RGB value of the color the user selected into this member. 
lpCustColors 
A pointer to the memory block which holds the list of 16 custom colors. 
Flags 
A combination of the following flags specifying how to create the Choose Color box: 
CC_ANYCOLOR = &H100 
Allow the user to select any color. 
CC_ENABLEHOOK = &H10 
Use the hook function specified by [pfnHook to process the Choose Color box's messages. 
CC_ENABLETEMPLATE = &H20 
Use the dialog box template identified by hInstance and lpTemplateName. 
CC_ENABLETEMPLATEHANDLE = &H40 
Use the preloaded dialog box template identified by hInstance, ignoring IpTemplateName. 
CC_FULLOPEN = &H2 
Automatically display the Define Custom Colors half of the dialog box. 
CC_PREVENTFULLOPEN = &H4 
Disable the button that displays the Define Custom Colors half of the dialog box. 
CC_RGBINIT = &H1 
Make the color specified by rgbResult be the initially selected color. 
CC_SHOWHELP = &H8 
Display the Help button. 
CC_SOLIDCOLOR = &H80 
Only allow the user to select solid colors. If the user attempts to select a non-solid color, 
convert it to the closest solid color. 
ICustData 
Application-defined value to pass to the hook function specified by [pfnHook whenever it is 
called. 
lpfnHook 
A pointer to the CCHookProc hook function to use to process the Choose Color box's messages. 
To have the dialog box process its own messages, set this to 0. 
lpTemplateName 
The name of the dialog box template to use in the module identified by hInstance. If this is not 
needed, set this to 0. 


Constant Definitions 


Const CC_ANYCOLOR = &H100 
Const CC_ENABLEHOOK = &H10 
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Const CC_ENABLETEMPLATE = &H20 

Const CC_ENABLETEMPLATEHANDLE = &H40 
Const CC_FULLOPEN = &H2 

Const CC_PREVENTFULLOPEN = &H4 

Const CC_RGBINIT = &H1 

Const CC_SHOWHELP = &H8 

Const CC_SOLIDCOLOR = &H80 


Used By 


ChooseColor 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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CHOOSEFONT_ TYPE Structure 


Type CHOOSEFONT_TYPE 
1StructSize As Long 
hwndOwner As Long 
hDC As Long 
lpLogFont As Long 
iPointSize As Long 
Flags As Long 
rgbColors As Long 
lCustData As Long 
lpfnHook As Long 
lpTemplateName As String 
hInstance As Long 
lpszStyle As String 
nFontType As Integer 
MISSING_ALIGNMENT As Integer 
nSizeMin As Long 
nSizeMax As Long 

End Type 


Description & Usage 


The CHOOSEFONT_TYPE structure is designed to pass information to and from the Choose Font 
common dialog box. Its members both specify initialization settings for rendering the box and receive 
information about the user's selection after the function completes. 


Visual Basic-Specific Issues 


Officially, this structure is called CHOOSEFONT. However, that violates the case-sensitive name 
spacing of Visual Basic because Visual Basic cannot then distinguish it from the ChooseFont API 


function. The Windows API Guide calls this structure CHOOSEFONT_TYPE to avoid the naming 
collision. 
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Data Members 


[StructSize 
The size in bytes of this structure. 
hwndOwner 
A handle to the window which is opening the Choose Font common dialog box, if any. 
hdc 
A handle to a device context or information context to the printer to read the printer fonts of. This 
must be specified if you want to display printer fonts in the font list. 
lpLogFont 
A pointer to a memory block which receives the contents of a LOGFONT structure specifying the 
attributes of the font the user selected. Optionally, this data block can also be initialized with the 
font to select by default in the dialog box. See the example for ChooseFont for how to obtain this 
address to a memory block. 
iPointSize 
The point size of the font, measured in units of !/,9 of a point (for example, 120 means 12 point). 
Flags 
A combination of the following flags specifying options for creating the Choose Font dialog box: 
CF_ANSIONLY 
List all fonts using a Windows or Unicode character set. Note: This flag is obsolete; use 
CF_SCRIPTSONLY instead. 
CF_APPLY 
Display and enable the Apply button. 
CF_BOTH 
List all printer and screen fonts. 
CF_EFFECTS 
Allow the strikeout, underline, and color attributes to be set. 
CF_ENABLEHOOK 
Use the hook function specified by [pfnHook to process the Choose Font dialog's 


messages. 
CF_ENABLETEMPLATE 

Use the dialog box template specified by IpTemplateName. 
CF_ENABLETEMPLATEHANDLE 

Use the preloaded dialog box template specified by hInstance. 
CF_FIXEDPITCHONLY 

List only fixed-pitch fonts. 
CF_FORCEFONTEXIST 

Do not allow the user to select a non-listed font. 
CF_INITTOLOGFONTSTRUCT 

Use the settings specified in JpLogFont to select a default font in the dialog box. 
CF_LIMITSIZE 
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Limit the point size selection to values between nSizeMin and nSizeMax inclusive. 


CF_NOOEMFONTS 

Same as CF_NOVECTORFONTS. 
CF_NOFACESEL 

Do not select a default font face name for the user. 
CF_NOSCRIPTSEL 

Do not select a default script setting for the user. 
CF_NOSIZESEL 

Do not select a default point size for the user. 
CF_NOSIMULATIONS 

Do not display a sample of the selected font. 
CF_NOSTYLESEL 

Do not select a default style for the user. 
CF_NOVECTORFONTS 

Do not list vector fonts. 
CF_NOVERTFONTS 

Do not list vertically-oriented fonts. 
CF_PRINTERFONTS 

List printer fonts. 
CF_SCALABLEONLY 

Only list scalable fonts. 
CF_SCREENFONTS 

List screen fonts. 
CF_SCRIPTSONLY 

List all fonts using a Windows or Unicode character set. 
CF_SELECTSCRIPT 

Only list fonts with the proper character set. 
CF_SHOWHELP 

Display the Help button. 
CF_TTONLY 

Only list TrueType fonts. 
CF_USESTYLE 

Use information in /pStyle to initialize the dialog box. 
CF_WYSIWYG 


List only fonts common to the printer and the screen (must be used with CF_BOTH and 


CF_SCALABLEONLY). 
rgbColors 
The RGB value for the color of the font. 
ICustData 
An application-defined parameter to pass to the hook function specified by /pfnHook. 
lpfnHook 


A pointer to a CFHookProc hook function used to process the dialog box's messages, if needed. 


lpTemplateName 
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The name of the dialog box template to use, if needed. 
hInstance 
A handle to the instance of the program that contains the pre-loaded dialog box template to use, if 
needed. 
IpszStyle 
Receives a string specifying the selected font's style settings. If used, this string must be large 
enough to receive the returned string. 
nFontType 
One or more of the following flags specifying the type of font that is selected: 
BOLD_FONTTYPE 
Boldface font. 
ITALIC_FONTTYPE 
Italicized font. 
PRINTER_FONTTYPE 
Printer font. 
REGULAR_FONTTY PE 
Regular font -- 1.e., not boldface. 
SCREEN_FONTTYPE 
Screen font. 
SIMULATED_FONTTYPE 
Font that can be simulated in the dialog box. 
MISSING_ALIGNMENT 
Never set this variable. It is there only to align the other members of the structure in memory. 
nSizeMin 
The minimum allowable point size selection, if applicable. 
nSizeMax 
The maximum allowable point size selection, if applicable. 


Constant Definitions 


Const CF_ANSIONLY = &H400 

Const CF_APPLY = &H200 

Const CF_BOTH = &H3 

Const CF_EFFECTS = &H100 

Const CF_ENABLEHOOK = &H8 

Const CF_ENABLETEMPLATE = &H10 
Const CF_ENABLETEMPLATEHANDLE = &H20 
Const CF_FIXEDPITCHONLY &H4000 
Const CF_FORCEFONTEXIST = &H10000 
Const CF_INITTOLOGFONTSTRUCT = &H40 
Const CF_LIMITSIZE = &H2000 

Const CF_NOOEMFONTS = &H800 


http://216.26.168.92/vbapi/ref/c/choosefont_type.html (4 of 5) [9/1/2002 5:56:03 PM] 


Windows API Guide: CHOOSEFONT_TYPE Structure 


Const CF_NOFACESEL = &H80000 
Const CF_NOSCRIPTSEL = &H800000 
Const CF_NOSIZESEL = &H200000 
Const CF_NOSIMULATIONS = &H1000 
Const CF_NOSTYLESEL = &H100000 
Const CF_NOVECTORFONTS = &H800 
Const CF_NOVERTFONTS = &H1000000 
Const CF_PRINTERFONTS &H2 
Const CF_SCALABLEONLY = &H20000 
Const CF_SCREENFONTS = &H1 

Const CF_SCRIPTSONLY = &H400 
Const CF_SELECTSCRIPT = &H400000 
Const CF_SHOWHELP = &H4 

Const CF_TTONLY = &H40000 

Const CF_USESTYLE = &H80 

Const CF_WYSIWYG = &H8000 

Const BOLD FONTTYPE = &H100 
Const ITALIC_FONTTYPE = &:H200 
Const PRINTER_FONTTYPE = &H4000 
Const REGULAR_FONTTYPE = &H400 
Const SCREEN _FONTTYPE = &H2000 
Const SIMULATED _FONTTYPE = &H8000 


Used By 


ChooseFont 
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CURRENCYFMT Structure 


Type CURRENCYFMT 
NumDigits As Long 
LeadingZero As Long 
Grouping As Long 
lpDecimalSep As String 
lpThousandSep As String 
NegativeOrder As Long 
PositiveOrder As Long 
lpCurrencySymbol As String 

End Type 


Description & Usage 


The CURRENCYFMT structure stores information about how to format a currency value for display. 
This structure allows a program to specify how it wants currency to be displayed, overriding the format 
used by a locale. 


Visual Basic-Specific Issues 


None. 


Data Members 


NumDigits 
The number of digits to display after the decimal point. 

LeadingZero 
If zero, do not pad the space to the right of the decimal point with zeros if there are fewer 
fractional digits than specified by NumDigits. If nonzero, then do pad the space. For example, if 
NumDigits is 3 and the number to display is $1.23, setting this data member to zero displays the 
number as "$1.23". Setting this data member to any other value displays "$1.230". 

Grouping 
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The number of digits to include in each group to the left of the decimal point. Typically, groups of 
three are used (e.g., $1,234,567). Values in the range of 0-9 are valid. 

IpDecimalSep 
The character to use for the decimal point. 

lpThousandSep 
The character to use for the grouping separator. 

NegativeOrder 
One of the following values specifying how to represent a negative currency value. An example 
of each choice is shown in the following list for the value of negative $1.1. 





0 

($1.1) 
1 

-$1.1 
2 

$-1.1 
3 

$1.1- 
4 

(1.1$) 
5 

-1.1$ 
6 

1.1-$ 
7 

1.1$- 
8 

-1.1 $ (space before $) 
9 

-$ 1.1 (space after $) 
10 

1.1 $- (space before $) 
11 

$ 1.1- (space after $) 
12 

$ -1.1 (space after $) 
13 

1.1- $ (space before $) 
14 

($ 1.1) (space after $) 
15 


(1.1 $) (space before $) 
PositiveOrder 
One of the following values specifying how to display a positive currency value. An example of 


http://216.26.168.92/vbapi/ref/c/currencyfmt.html (2 of 3) [9/1/2002 5:56:08 PM] 


Windows API Guide: CURRENCYFMT Structure 


each choice is shown in the following list for the value of $1.1. 


0 
$1.1 
1 
1.1$ 
2 
$ 1.1 (space after $) 
3 


1.1 $ (space before $) 
lpCurrencySymbol 
The symbol used to represent the currency. For example, US dollars are typically represented by 
the $ character. 


Used By 


GetCurrencyFormat 


Back to the Structure list. 
Back to the Reference section. 
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DEVMODE Structure 


Type DEVMODE 
dmDeviceName As String * 32 
dmSpecVersion As Integer 
dmDriverVersion As Integer 
dmSize As Integer 
dmDriverExtra As Integer 
dmFields As Long 
dmOrientation As Integer 
dmPaperSize As Integer 
dmPaperLength As Integer 
dmPaperWidth As Integer 
dmScale As Integer 
dmCopies As Integer 
dmDefaultSource As Integer 
dmPrintQuality As Integer 
dmColor As Integer 
dmDuplex As Integer 
dmYResolution As Integer 
dmTTOption As Integer 
dmCollate As Integer 
dmFormName As String * 32 
dmUnusedPadding As Integer 
dmBitsPerPixel As Integer 
dmPelsWidth As Long 
dmPelsHeight As Long 
dmDisplayFlags As Long 
dmDisplayFrequency As Long 
' The following only appear in Windows 95, 98, 2000 
dmICMMethod As Long 
dmICMIntent As Long 
dmMediaType As Long 
dmDitherType As Long 
dmReservedl As Long 
dmReserved2 As Long 
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' The following only appear in Windows 2000 
dmPanningWidth As Long 
dmPanningHeight As Long 

End Type 


Description & Usage 


The DEVMODE structure stores information about various settings and properties of a device, such as a 
printer. Some of the properties only apply to certain devices; for example, the dmDisplayFrequency has 
no relevant meaning for a printer. To determine which data members of the structure contain useful 
information, check the flags set in dwFields. 


Visual Basic-Specific Information 


None. 


Data Members 


dmDeviceName 
The name of the device. 
dmSpecVersion 
The version number of the device's initialization information specification. 
dmDriverVersion 
The version number of the device driver. 
dmSize 
The size of the structure, in bytes. 
dmDriverExtra 
The number of bytes of information trailing the structure in memory. 
dmFields 
A combination of the following flags specifying which of the rest of the structure's members 
contain information about the device: 
DM_ORIENTATION 
dmOrientation contains information. 
DM_PAPERSIZE 
dmPaperSize contains information. 
DM_PAPERLENGTH 
dmPaperLength contains information. 
DM_PAPERWIDTH 
dmPaperWidth contains information. 
DM_SCALE 
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dmScale contains information. 
DM_COPIES 

dmCopies contains information. 
DM_DEFAULTSOURCE 

dmDefaultSource contains information. 
DM_PRINTQUALITY 

dmPrintQuality contains information. 
DM_COLOR 

dmColor contains information. 
DM_DUPLEX 

dmDuplex contains information. 
DM_YRESOLUTION 

dmYResolution contains information. 
DM_TTOPTION 

dmTTOption contains information. 
DM_COLLATE 

dmCollate contains information. 
DM_FORMNAME 

dmFormName contains information. 
DM_LOGPIXELS 

dmLog Pixels contains information. 
DM_BITSPERPEL 

dmBitsPerPel contains information. 
DM_PELSWIDTH 

dmPelsWidth contains information. 
DM_PELSHEIGHT 

dmPelsHeight contains information. 
DM_DISPLAYFLAGS 

dmDisplayFlags contains information. 
DM_DISPLAYFREQUENCY 

dmDisplay Frequency contains information. 
DM_ICMMETHOD 

Win 95/98 only: dmICMMethod contains information. 
DM_ICMINTENT 

Windows 95, 98, 2000: dmICMIntent contains information. 
DM_MEDIATYPE 

Windows 95, 98, 2000: dmMediaType contains information. 
DM_DITHERTYPE 

Windows 95, 98, 2000: dmDitherType contains information. 
DM_PANNINGWIDTH 

Windows 2000: dmPanning Width contains information. 
DM_PANNINGHEIGHT 

Windows 2000: dmPanningHeight contains information. 
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dmOrientation 

One of the following flags specifying the orientation of the printer paper: 
DMORIENT_PORTRAIT 

Portrait (tall) mode. 
DMORIENT_LANDSCAPE 

Landscape (wide) mode. 

dmPaperSize 

If nonzero, one of the following flags specifying the size of the printer paper (or some other value 
specifying a paper size). If zero, the paper size is determined by dmPaperLength and 
dmPaperWidth. 
DMPAPER_LETTER 

Letter, 8.5 x 11 inches. 
DMPAPER_LEGAL 

Legal, 8.5 x 14 inches. 
DMPAPER_10X11 

10 x 11 inches. 
DMPAPER_ 10X14 

10 x 14 inches. 
DMPAPER_11X17 

11 x 17 inches. 
DMPAPER_ 15X11 

15 x 11 inches. 
DMPAPER_9X11 

9 x 11 inches. 
DMPAPER_A_PLUS 

A plus sheet. 
DMPAPER_A2 

A2 sheet. 
DMPAPER_A3 

A3 sheet, 297 x 420 millimeters. 
DMPAPER_A3_EXTRA 

A3 extra sheet. 
DMPAPER_A3_EXTRA_TRANSVERSE 

A3 extra transverse sheet. 
DMPAPER_A3_TRANSVERSE 

A3 transverse sheet. 
DMPAPER_A4 

A4 sheet, 210 x 297 millimeters. 
DMPAPER_A4_EXTRA 

A4 extra sheet. 
DMPAPER_A4_PLUS 

A4 plus sheet. 
DMPAPER_A4_ TRANSVERSE 


http://216.26.168.92/vbapi/ref/d/devmode.html (4 of 14) [9/1/2002 5:56:14 PM] 


Windows API Guide: DEVMODE Structure 


A4 transverse sheet. 
DMPAPER_A4SMALL 

A4 small sheet, 210 x 297 millimeters. 
DMPAPER_A5 

AS sheet, 148 x 210 millimeters. 
DMPAPER_A5 EXTRA 

A5 extra sheet. 
DMPAPER_A5_ TRANSVERSE 

A5 transverse sheet. 
DMPAPER_B_ PLUS 

B plus sheet. 
DMPAPER_B4 

B4 sheet, 250 x 354 millimeters. 
DMPAPER_B5 

B5 sheet, 192 x 257 millimeters. 
DMPAPER_B5 EXTRA 

B5 extra sheet. 
DMPAPER_B5_ TRANSVERSE 

B5 transverse sheet. 
DMPAPER_CSHEET 

C sheet, 17 x 22 inches. 
DMPAPER_ DSHEET 

D sheet, 22 x 34 inches. 
DMPAPER_ENV_10 

#10 envelope, 4.125 x 9.5 inches. 
DMPAPER_ENV_11 

#11 envelope, 4.5 x 10.375 inches. 
DMPAPER_ENV_12 

#12 envelope, 4.75 x 11 inches. 
DMPAPER_ENV_ 14 

#14 envelope, 5 x 11.5 inches. 
DMPAPER_ ENV_9 

#9 envelope, 3.875 x 8.875 inches. 
DMPAPER_ENV_B4 

B4 envelope, 250 x 353 millimeters. 
DMPAPER_ENV_BS5 

B5 envelope, 176 x 250 millimeters. 
DMPAPER_ENV_B6 

B6 envelope, 176 x 125 millimeters. 
DMPAPER_ENV_C3 

C3 envelope, 324 x 458 millimeters. 
DMPAPER_ENV_C4 

C4 envelope, 229 x 324 millimeters. 


http://216.26.168.92/vbapi/ref/d/devmode.html (5 of 14) [9/1/2002 5:56:14 PM] 


Windows API Guide: DEVMODE Structure 


DMPAPER_ ENV_C5 

C5 envelope, 162 x 229 millimeters. 
DMPAPER_ ENV_C6 

C6 envelope, 114 x 162 millimeters. 
DMPAPER_ENV_C65 

C65 envelope, 114 x 229 millimeters. 
DMPAPER_ ENV_DL 

DL envelope, 110 x 220 millimeters. 
DMPAPER_ENV_INVITE 

Invitation envelope. 
DMPAPER_ ENV_ITALY 

Italy envelope, 110 x 230 millimeters. 
DMPAPER_ ENV_MONARCH 

Monarch envelope, 3.875 x 7.5 inches. 
DMPAPER_ENV_PERSONAL 

Personal (6.75) envelope, 3.625 x 6.5 inches. 
DMPAPER_ESHEET 

E sheet, 34 x 44 inches. 
DMPAPER_ EXECUTIVE 

Executive, 7.25 x 10.5 inches. 
DMPAPER FANFOLD_LGL_ GERMAN 

German legal fanfold, 8.5 x 13 inches. 
DMPAPER_ FANFOLD_STD_GERMAN 

German standard fanfold, 8.5 x 12 inches. 
DMPAPER_ FANFOLD_US 

US standard fanfold, 14.875 x 11 inches. 
DMPAPER_FIRST 

Same as DMPAPER_ LETTER. 
DMPAPER_ FOLIO 

Folio, 8.5 x 13 inches. 
DMPAPER_ISO_B4 

ISO B4 sheet. 
DMPAPER_ JAPANESE POSTCARD 

Japanese postcard. 
DMPAPER_ LAST 


Same as DMPAPER_FANFOLD_LGL_GERMAN. 


DMPAPER_LEDGER 

Ledger, 17 x 11 inches. 
DMPAPER_LEGAL_EXTRA 

Legal extra. 
DMPAPER_LETTER_EXTRA 

Letter extra. 
DMPAPER_LETTER_EXTRA_TRANSVERSE 
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Letter extra transverse. 
DMPAPER_LETTER_PLUS 
Letter plus. 
DMPAPER_LETTER_TRANSVERSE 
Letter transverse. 
DMPAPER_LETTERSMALL 
Letter small, 8.5 x 11 inches. 
DMPAPER_NOTE 
Note, 8.5 x 11 inches. 
DMPAPER_QUARTO 
Quarto, 215 x 275 millimeters. 
DMPAPER_STATEMENT 
Statement, 5.5 x 8.5 inches. 
DMPAPER_TABLOID 
Tabloid, 11 x 17 inches. 
DMPAPER_TABLOID_EXTRA 
Tabloid extra. 
DMPAPER_USER 
User-defined size. 
dmPaperLength 
The length of the printer paper, measured in tenths of a millimeter. 
dmPaperWidth 
The width of the printer paper, measured in tenths of a millimeter. 
dmScale 
The scale percentage factor (e.g., 100 means 100%, or no, scaling; 200 means two times the size, 
etc.). 
dmCopies 
The number of document copies to print, if the device supports it. 
dmDefaultSource 
One of the following flags specifying the printer's source of paper: 
DMBIN_ONLYONE 
There is only one paper source. 
DMBIN_UPPER 
Upper bin. 
DMBIN_LOWER 
Lower bin. 
DMBIN_MIDDLE 
Middle bin. 
DMBIN_MANUAL 
Manual loading. 
DMBIN_ENVELOPE 
Envelope bin. 
DMBIN_ENVMANUAL 
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Manual-loading envelope. 
DMBIN_AUTO 
Automatic loading. 
DMBIN_TRACTOR 
Tractor loading. 
DMBIN_SMALLFMT 
Small format loading. 
DMBIN_LARGEFMT 
Large format loading. 
DMBIN_LARGECAPACITY 
Large-capacity bin. 
DMBIN_CASSETTE 
Cassette. 
DMBIN_FORMSOURCE 
Form paper source. 
dmPrintQuality 
Either one of the following flags specifying the printer's print quality setting, or a positive value 
specifying the printer's dots per inch (DPI) rating. 
DMRES_DRAFT 
Draft-quality output. 
DMRES_LOW 
Low-quality output. 
DMRES_MEDIUM 
Medium-quality output. 
DMRES_HIGH 
High-quality output. 
dmColor 
One of the following flags specifying whether the device supports color: 
DMCOLOR_MONOCHROME 
The device does not support color output. 
DMCOLOR_COLOR 
The device supports color output. 
dmDuplex 
One of the following flags specifying the printer's double-sided (duplex) printing capability: 
DMDUP_SIMPLEX 
Configured for single-sided printing. 
DMDUP_VERTICAL 
Configured for double-sided printing with vertical page turning. 
DMDUP_HORIZONTAL 
Configured for double-sided printing with horizontal page turning. 
dmYResolution 
The number of the vertical dots per inch of the printer. If this value contains useful data, the 
number of horizontal dots per inch is inside dmPrintQuality. 


http://216.26.168.92/vbapi/ref/d/devmode.html (8 of 14) [9/1/2002 5:56:14 PM] 


Windows API Guide: DEVMODE Structure 


dmTTOption 
One of the following flags specifying how the printer prints TrueType fonts: 
DMTT_BITMAP 
The printer prints TrueType fonts as graphics (default for dot-matrix printers). 
DMTT_DOWNLOAD 
The printer downloads TrueType fonts as soft fonts (default for Hewlett-Packerd printers 
using Printer Control Language). 
DMTT_SUBDEV 
The printer substitutes device fonts for TrueType fonts (default for PostScript printers). 
dmUnusedPadding 
Reserved -- set to 0. This member merely takes up space to align other members in memory. 
dmCollate 
One of the following flags specifying whether the printer can collate copies: 
DMCOLLATE_FALSE 
Does not collate pages when printing multiple copies. 
DMCOLLATE_TRUE 
Does collate pages when printing multiple copies. 
dmFormName 
Windows NT, 2000: The name of the type of paper loaded in the printer. 
dmBitsPerPel 
The number of color bits used per pixel on the display device. 
dmPels Width 
The width of the display, measured in pixels. 
dmPelsHeight 
The height of the display, measured in pixels. 
dmDisplayFlags 
A combination of the following flags specifying the device's display mode: 
DM_GRAYSCALE 
The display does not support color. (If this flag is omitted, assume color is supported.) 
DM_INTERLACED 
The display is interlaced. 
dmDisplayFrequency 
The display frequency of the display, measured in Hz. 
dmICMMethod 
Windows 95, 98, 2000: Either one of the following flags specifying how image color matching 
(ICM) is supported, or a device-defined value greater than 256: 
DMICMMETHOD_NONE 
ICM is disabled. 
DMICMMETHOD_SYSTEM 
ICM is handled by Windows. 
DMICMMETHOD_DRIVER 
ICM is handled by the device driver. 
DMICMMETHOD_DEVICE 
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ICM is handled by the device. 
dmICMIntent 
Windows 95, 98, 2000: Either one of the following flags specifying the image color matching 
(ICM) method used when ICM is not intrinsically supported, or a device-defined value greater 
than 256: 
DMICM_SATURATE 
Color matching attempts to optimize color saturation. 
DMICM_CONTRAST 
Color matching attempts to optimize color contrast. 
DMICM_COLORMETRIC 
Color matching attempts to match the exact color requested. 
dmMediaType 
Windows 95, 98, 2000: Either one of the following flags specifying what type of medium the 
printer is printing on, or a device-defined value greater than 256: 
DMMEDIA_STANDARD 
Plain paper. 
DMMEDIA_GLOSSY 
Glossy paper. 
DMMEDIA_TRANSPARECNY 
Transparent film. 
dmDitherType 
Windows 95, 98, 2000: Either one of the following flags specifying the dithering method used by 
the device, or a device-defined value greater than 256: 
DMDITHER_NONE 
No dithering. 
DMDITHER_COARSE 
Dithering with a coarse brush. 
DMDITHER_FINE 
Dithering with a fine brush. 
DMDITHER_LINEART 
Line art dithering, which makes well-defined borders between black, white, and gray. 
DMDITHER_GRAYSCALE 
Grayscaling. 
dmReservedl 
Windows 95, 98, 2000: Reserved -- set to 0. 
dmReserved2 
Windows 95, 98, 2000: Reserved -- set to 0. 
dmPanning Width 
Windows 2000: Reserved -- set to 0. 
dmPanningHeight 
Windows 2000: Reserved -- set to 0. 
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Constant Definitions 


Const DM_ORIENTATION = &H1 

Const DM_PAPERSIZE = &H2 

Const DM _PAPERLENGTH = &H4 

Const DM_PAPERWIDTH = &H8 

Const DM_SCALE = &H10 

Const DM_COPIES = &H100 

Const DM_DEFAULTSOURCE = &H200 
Const DM _PRINTQUALITY = &H400 
Const DM_COLOR = &H800 

Const DM DUPLEX = &H1000 

Const DM_YRESOLUTION = &H2000 
Const DM_TTOPTION = &H4000 

Const DM_COLLATE = &H8000 

Const DM_FORMNAME = &H10000 

Const DM_LOGPIXELS = &H20000 

Const DM_BITSPERPEL = &H40000 
Const DM_PELSWIDTH = &H80000 

Const DM _PELSHEIGHT = &H100000 
Const DM_DISPLAYFLAGS = &H200000 
Const DM _DISPLAYFREQUENCY = &H400000 
Const DM_ICMMETHOD = &H800000 
Const DM_ICMINTENT &H1O000000 
Const DM MEDIATYPE &H2Z2000000 
Const DM_DITHERTYPE = &H4000000 
Const DM_PANNINGWIDTH = &H20000000 
Const DM _PANNINGHEIGHT = &H40000000 
Const DMORIENT_ PORTRAIT = 1 

Const DMORIENT_LANDSCAPE = 2 

Const DMPAPER_ LETTER = 1 

Const DMPAPER_ LEGAL 5 

Const DMPAPER_10X11 = 45 

Const DMPAPER_10X14 = 16 

Const DMPAPER_11X17 = 17 

Const DMPAPER_15X11 = 46 

Const DMPAPER_ 9X11 = 44 

Const DMPAPER_ A PLUS = 57 

Const DMPAPER_ A2 = 66 

Const DMPAPER A3 = 8 

Const DMPAPER_A3_EXTRA = 63 

Const DMPAPER_A3_ EXTRA TRANSVERSE = 68 
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Const DMPAPER_A3_TRANSVERSE 67 
Const DMPAPER_A4 = 9 

Const DMPAPER_A4 EXTRA = 53 
Const DMPAPER_A4 PLUS = 60 

Const DMPAPER_A4_ TRANSVERSE 55 
Const DMPAPER_A4SMALL = 10 

Const DMPAPER_A5 = 11 

Const DMPAPER_A5_ EXTRA = 64 
Const DMPAPER_A5_ TRANSVERSE 61 
Const DMPAPER_B_ PLUS = 58 

Const DMPAPER_B4 = 12 

Const DMPAPER_B5 = 13 

Const DMPAPER_B5_EXTRA = 65 
Const DMPAPER_B5_TRANSVERSE 62 
Const DMPAPER_CSHEET = 24 

Const DMPAPER_DSHEET = 25 

Const DMPAPER_ENV_10 = 20 

Const DMPAPER_ENV_11 = 21 

Const DMPAPER_ENV_12 = 22 

Const DMPAPER_ENV_14 = 23 

Const DMPAPER_ENV_9 = 19 

Const DMPAPER_ENV_B4 = 33 

Const DMPAPER_ENV_B5 = 34 

Const DMPAPER_ENV_B6é = 35 

Const DMPAPER_ENV_C3 = 29 

Const DMPAPER_ENV_C4 = 30 

Const DMPAPER_ENV_C5 = 28 

Const DMPAPER_ENV_C6 = 31 

Const DMPAPER_ENV_C65 = 32 

Const DMPAPER_ENV_DL = 27 

Const DMPAPER_ENV_INVITE = 47 
Const DMPAPER_ENV_ITALY = 36 
Const DMPAPER_ENV_MONARCH = 37 
Const DMPAPER_ENV_PERSONAL = 38 
Const DMPAPER_ESHEET = 26 

Const DMPAPER_EXECUTIVE = 7 
Const DMPAPER_FANFOLD_LGL_GERMAN = 41 
Const DMPAPER_FANFOLD_STD_GERMAN = 40 
Const DMPAPER_FANFOLD_US = 39 
Const DMPAPER_FIRST = 1 

Const DMPAPER_FOLIO = 14 

Const DMPAPER_ISO_B4 = 42 

Const DMPAPER_JAPANESE POSTCARD = 43 
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Const DMPAPER_LAST = 41 
Const DMPAPER_LEDGER = 4 
Const DMPAPER_LEGAL_EXTRA = 51 
Const DMPAPER_LETTER_EXTRA = 50 





Const DMPAPER_LETTER_EXTRA_TRANSVERSE = 





Const DMPAPER_ LETTER_PLUS = 59 
Const DMPAPER_LETTER_TRANSVERSE = 54 
Const DMPAPER_LETTERSMALL = 2 
Const DMPAPER_ NOTE = 18 

Const DMPAPER_QUARTO = 15 
Const DMPAPER_ STATEMENT = 6 
Const DMPAPER_ TABLOID = 3 
Const DMPAPER_TABLOID_EXTRA = 52 
Const DMPAPER_USER = 256 

Const DMBIN_ONLYONE = 1 

Const DMBIN_UPPER = 1 

Const DMBIN_ LOWER = 2 

Const DMBIN_ MIDDLE = 3 

Const DMBIN_ MANUAL = 4 

Const DMBIN_ENVELOPE = 5 

Const DMBIN_ENVMANUAL = 6 
Const DMBIN_AUTO = 7 

Const DMBIN_TRACTOR = 8 

Const DMBIN_SMALLFEMT 9 

Const DMBIN_LARGEFMT = 10 
Const DMBIN_LARGECAPACITY = 11 
Const DMBIN_CASSETTE = 14 
Const DMBIN_FORMSOURCE = 15 
Const DMRES_DRAFT = -1 

Const DMRES_LOW = -2 

Const DMRES_MEDIUM = -3 

Const DMRES_HIGH = -4 

Const DMCOLOR_MONOCHROME = 1 
Const DMCOLOR_COLOR = 2 

Const DMDUP_SIMPLEX = 1 

Const DMDUP_VERTICAL = 2 

Const DMDUP_HORIZONTAL = 3 
Const DMTT_BITMAP = 1 

Const DMTT_DOWNLOAD = 2 

Const DMTT_SUBDEV = 4 

Const DMCOLLATE_FALSE = 0 
Const DMCOLLATE_TRUE = 1 

Const DM_GRAYSCALE = 1 
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Const DM_INTERLACED = 2 
Const DMICMMETHOD_NONE = 1 
Const DMICMMETHOD_ SYSTEM = 2 
Const DMICMMETHOD DRIVER 
Const DMICMMETHOD_ DEVICE = 4 
Const DMICM_SATURATE 1 

Const DMICM_CONTRAST = 2 

Const DMICM_COLORMETRIC = 3 
Const DMMEDIA STANDARD = 1 
Const DMMEDIA GLOSSY = 2 

Const DMMEDIA TRANSPARECNY = 3 
Const DMDITHER_ NONE = 1 

Const DMDITHER_COARSE = 2 
Const DMDITHER_FINE = 3 

Const DMDITHER_LINEART = 4 
Const DMDITHER_GRAYSCALE = 5 


Used By 


ChangeDisplaySettings, CreateDC, EnumDisplaySettings, JOB_INFO_2, PRINTDLG_TYPE, 
PRINTER DEFAULTS, PRINTER INFO 2 


II 
W 























Go back to the Structure listing. 
Go back to the Reference section index. 


Last Modified: January 21, 2001 

This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/d/devmode.html 
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vbapi.com - part of the VB-World Network 
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DEVNAMES Structure 


Type DEVNAMES 
wDriverOffset As Integer 
wDeviceOffset As Integer 
wOutputOffset As Integer 
wDefault As Integer 
extra As String * 100 

End Type 


DEVNAMES-type variables store some information about a device. This information includes the 
device driver name, the device name, and the names of any output ports it uses. Note that instead of 
storing strings in the usual way, this structure puts all three strings into extra, where null characters 
separate them. The offset values specify the location of these strings in extra, measured in bytes from the 
beginning of the structure. For example, the very first character in extra would have an offset of 8. See 
the example for the PrintDlg function for a demonstration of using this structure. 


wDriverOffset 
The offset of the string in extra identifying the name of the device driver filename (without the 
extension). 

wDevice Offset 
The offset of the string in extra identifying the name of the device. 

wOutputOffset 
The offset of the string in extra identifying the output port(s) which the device uses, separated by 
commas. 

wDefault 
If non-zero, the information in the structure identifies the default device of its type. If zero, the 
information does not necessarily descibe the default device. 

extra 
Buffer which holds the three strings identified by wDriverOffset, wDeviceOffset, and 
wOutputOffset. 


Used by: PRINTDLG_TYPE 


Go back to the alphabetical Structure listing. 
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Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 
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DOCINFO Structure 


Type DOCINFO 
cbSize As Long 
lpszDocName As String 
lpszOutput As Long 
lpszDatatype As String 
fwType As Long 

End Type 


Description & Usage 


The DOCINFO structure holds information about a print job. This information is mainly used to give a 
description of the document to the print spooler. It also specifies whether to send the data to the printer or 
to a print file, as well as specifying a few additional options. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 
The size in bytes of the structure. 
lpszDocName 
The name of the document being printed. 
IpszOutput 
To send the output to a print file, this is a pointer to a null-terminated string identifying the file to 
create. To send the output to the printer itself, set this to 0. 
lpszDatatype 
The data type of the document being printed, if applicable. 
fwType 
Zero or more of the following flags specifying additional options for printing: 
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DI_APPBANDING 

If the program uses banding, set this flag to provide optimal performance during printing. 
DI_ROPS_READ_DESTINATION 

Use raster operations which involve reading the destination surface. 


Constant Definitions 


Const DI_APPBANDING = &H1 
Const DI_ROPS_READ_ DESTINATION = &H2 


Used By 


StartDoc 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 


Last Modified: November 2, 1999 

This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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ENUMLOGFONT Structure 


Type ENUMLOGFONT 
elfLogFont As LOGFONT 
elfFullName As String * 64 
elfStyle As String * 64 
End Type 


Description & Usage 


The ENUMLOGFONT structure holds information about a logical font which has been enumerated. 


The structure not only idenifies the regular logical font information but also some additional information 
as well. Windows 95, 98: If the font is not a TrueType font, the el/fLogFont member must be used to get 
all of the font's information. The other data members of this structure will not contain any useful data. 


Visual Basic-Specific Issues 


None. 


Data Members 


elfLogFont 
Logical font information about the enumerated font. 

elfFullName 
A null-terminated string identifying the full name of the enumerated font. Windows 95, 98: If the 
font is not a TrueType font, this string does not contain any useful information. 

elfStyle 
A null-terminated string identifying the style attributes of the enumerated font. Windows 95, 98: 
If the font is not a TrueType font, this string does not contain any useful information. 


Used By 
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EnumFontFamProc 
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ENUMLOGFONTEX Structure 


Type ENUMLOGFONTEX 
elfLogFont As LOGFONT 
elfFullName As String * 64 
elfStyle As String * 32 
elfScript As String * 32 

End Type 


Description & Usage 


The ENUMLOGFONTEX structure holds information about a logical font which has been enumerated. 
The structure not only idenifies the regular logical font information but also some additional information 
as well. Windows 95, 98: If the font is not a TrueType font, the el/fLogFont member must be used to get 
all of the font's information. The other data members of this structure will not contain any useful data. 


Visual Basic-Specific Issues 


None. 


Data Members 


elfLogFont 
Logical font information about the enumerated font. 

elfFullName 
A null-terminated string identifying the full name of the enumerated font. Windows 95, 98: If the 
font is not a TrueType font, this string does not contain any useful information. 

elfStyle 
A null-terminated string identifying the style attributes of the enumerated font. Windows 95, 98: 
If the font is not a TrueType font, this string does not contain any useful information. 

elfScript 
A null-terminated string identifying the character set of the enumerated font. Windows 95, 98: If 
the font is not a TrueType font, this string does not contain any useful information. 
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Used By 
EnumFontFamExProc 
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FILETIME Structure 


Type FILETIME 
dwLowDateTime As Long 
dwHighDateTime As Long 

End Type 


Description & Usage 


The FILETIME structure holds a date and time associated with a file. The structure identifies a 64-bit 
integer specifying the number of 100-nanosecond intervals which have passed since January 1, 1601. 
This 64-bit value is split into the two dwords stored in the structure. 





Visual Basic-Specific Issues 


None. 


Parameters 


dwLowDateTime 

The low-order dword of the 64-bit integer specifying the date and time. 
dwHighDateTime 

The high-order dword of the 64-bit integer specifying the date and time. 


Used By 


BY_HANDLE_FILE INFORMATION, CompareFileTime, FileTimeToLocalFileTime, 
FileTimeToSystemTime, GetFileTime, GetSystemTimeAsFileTime, LocalFileTimeToFileTime, 
RegEnumKeyEx, SetFileTime, SystemTimeToFileTime, WIN32_FIND_DATA 


Go back to the alphabetical Structure listing. 
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FILTERKEYS Structure 


Type FILTERKEYS 
cbhSize As Long 
dwFlags As Long 
iWaitMSec As Long 
iDelayMSec As Long 
iRepeatMSec As Long 
iBounceMSec As Long 

End Type 


FILTERKEYS-type variables store information relating to the FilterKeys accessibility feature. 
FilterKeys helps filter out unwanted and accidental keypresses by controlling settings such as the repeat 
rate and requiring keys to be held for a certain time before they are accepted. This structure stores the 
settings of FilterKeys. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various FilterKeys settings and properties: 
FKF_AVAILABLE = &H2 
The FilterKeys accessibility feature is available. 
FKF_CLICKON = &H40 
Play a clicking sound whenever a key is pressed or accepted. 
FKF_CONFIRMHOTKEY = &H8 
Win 95/98 only: Display a confirmation dialog whenever the user activates FilterKeys via 
the hot key. 
FKF_FILTERKEYSON = &H1 
FilterKeys is currently on. 
FKF_HOTKEYACTIVE = &H4 
The user can toggle FilterKeys by using the hot key: holding the right Shift key for eight 
seconds. 
FKF_HOTKEYSOUND = &H10 
Play a sound when the user toggles FilterKeys via the hot key. 
FKF_INDICATOR = &H20 
Win 95/98 only: Display an icon in the tray while FilterKeys in on. 
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iWaitMSec 

The length of time, in milliseconds, the user must hold down a key before it is accepted. 
iDelayMSec 

The length of time, in milliseconds, the user must hold down a key before it begins to repeat. 
iRepeatM Sec 

The length of time, in milliseconds, between each repetition of a key. 
iBounceMSec 

The length of time, in milliseconds, before subsequent presses of the same key will be accepted. 


Used by: SystemParametersInfo 
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FONTSIGNATURE Structure 


Type FONTSIGNATURE 
fsUsb(0 To 3) As Long 
fsCsb(0 To 1) As Long 

End Type 


Description & Usage 


The FONTSIGNATURE structure holds the font signature of a font. The font signature is composed of 
a 128-bit Unicode subset bitfield (USB) and a 64-bit code-page bitfield (CPB). Both of these values are 
split into multi-element arrays of 32-bit integers. For each array, the lowest-order dword appears as the 
first array element, and the highest-order dword appears as the last array element. 


Visual Basic-Specific Issues 


None. 


Data Members 


fsUsb 
A Unicode subset bitfield (USB), a 128-bit value, identifying up to 126 Unicode subranges. Each 
bit except the two most significant ones identify one of 126 possibly Unicode subranges, 
according to the ISO 10646 standard. 

fsCsb 
A code-page bitfield (CPB), a 64-bit value, identifying a specific character set or code page. 
Windows code pages are in the low-order dword; non-Windows code pages are in the high-order 
dword. 


Used By 


NEWTEXTMETRICEX 
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HARDWAREINPUT Structure 


Type HARDWAREINPUT 
uMsg As Long 
wParamL As Integer 
wParamH As Integer 

End Type 


Description & Usage 


The HARDWAREINPUT structure holds information about a message synthesized by some generic 
(non-keyboard, non-mouse) input hardware. The data members of the structure specify the information 
associated with the message generated. 


Visual Basic-Specific Issues 


None. 


Data Members 


uMsg 

The message identifier of the message generated by the input hardware. 
wParamL 

The low-order word of the message's first parameter. 
wParamH 

The high-order word of the message's first parameter. 


Used By 
INPUT_TYPE 


Go back to the alphabetical Structure listing. 
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HELPINFO Structure 


Type HELPINFO 
cbhSize As Long 
iContextType As Long 
iCtrliId As Long 
hitemHandle As Long 
dwContextId As Long 
MousePos As POINT TYPE 

End Type 





Description & Usage 


The HELPINFO structure holds information about a help request. The structure holds details about the 
object or other item about which help information is requested by the user. The structure does not specify 
the help documentation itself, but rather the object for which context-sensitive help is wanted. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 
The size in bytes of the structure. 
iContextT ype 
One of the following flags specifying the type of context for which help information is requested: 
HELPINFO_MENUITEM 
Help information is requested for a menu item. 
HELPINFO_WINDOW 
Help information is requested for a control or window. 
iCtrlld 
An identifier of the window, control, or menu item for which context-sensitive help is desired. 
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hItemHandle 
A handle to the window or control (if iContextType is HELPINFO_WINDOW) or an identifier of 
the associated menu (if iContextType is HELPINFO_MENUITEM) for which context-sensitive 
help is desired. 

dwContextld 
The help context identifier of the window or control. 

MousePos 
The coordinates of the mouse cursor when help information was requested. 


Constant Definitions 


Const HELPINFO_MENUITEM 2 


Const HELPINFO_WINDOW = 1 


Used By 


MsgBoxCallback, WM_HELP 
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HELPWININEFO Structure 


Type HELPWININFO 

wStructSize As Long 

x As Long 

y As Long 

dx As Long 

dy As Long 

wMax As Long 

rgchMember As String * 2 
End Type 


Description & Usage 


The HELPWININFO structure holds information about the size and position of a primary or secondary 
Windows Help window. This information is used to reposition such a window. "Normal" screen 
coordinates are not used by this structure! Instead, the screen is divided into 1024 units both horizontally 
and vertically (regardless of the actual resolution). This coordinate system is used by the data members 
which specify coordinates. 


Visual Basic-Specific Issues 


None. 


Data Members 


wStructSize 

The size in bytes of the structure. 
x 

The x-coordinate of the upper-left corner of the window. 
y 

The y-coordinate of the upper-left corner of the window. 
dx 


http://216.26.168.92/vbapi/ref/h/helpwininfo.html (1 of 3) [9/1/2002 5:57:10 PM] 


Windows API Guide: HELPWININFO Structure 


The width of the window. 
dy 
The height of the window. 
wMax 
Exactly one of the following flags specifying how to show the window: 
SW_HIDE 
Hide the window and make a different window the active window. 
SW_MINIMIZE 
Minimize the window and activate the top window in the z-order. 
SW_RESTORE 
Same as SW_SHOWNORMAL. 
SW_SHOW 
Activate the window and display it in its current size and position. 
SW_SHOWMAXIMIZED 
Activate and maximize the window. 
SW_SHOWMINIMIZED 
Activate and minimize the window. 
SW_SHOWMINNOACTIVE 
Minimize the window, leaving whichever window was previously the active window 
active. 
SW_SHOWNA 
Display the window in its current size and position, leaving whichever window was 
previously the active window active. 
SW_SHOWNOACTIVATE 
Display the window in its most recent size and position, leaving whichever window was 
previously the active window active. 
SW_SHOWNORMAL 
Activate and display the window, restoring it to its original size and position. 
rgchMember 
The name of the window to set the size and position of. 


Constant Definitions 


Const SW_HIDE = 0 

Const SW_MINIMIZE = 6 

Const SW_RESTORE = 9 

Const SW_SHOW = 5 

Const SW_SHOWMAXIMIZED = 3 
Const SW_SHOWMINIMIZED = 2 
Const SW_SHOWMINNOACTIVE = 7 
Const SW_SHOWNA = 8 

Const SW_SHOWNOACTIVATE = 4 
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Const SW_SHOWNORMAL = 1 


Used By 
WinHelp 
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HIGHCONTRAST Structure 


Type HIGHCONTRAST 
cbhSize As Long 
dwFlags As Long 
lpszDefaultScheme As String 
End Type 


HIGHCONTRAST-type variables store information about the HighContrast accessibility feature. 
HighContrast aids users with poor vision by utilizing a high-contrast Windows color scheme to maximize 
visibility. The structure stores the settings for the HighContrast accessibility feature. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various settings and properties of HighContrast: 
HCF_AVAILABLE = &H2 
The HighContrast accessibility feature is available. 
HCF_CONFIRMHOTKEY = &H8 
Open a confirmation dialog box when the user activates HighContrast via the hot key. 
HCF_HIGHCONTRASTON = &H1 
HighContrast is currently on. 
HCF_HOTKEYACTIVE = &H4 
Allow the user to toggle HighContrast using the hot key: pressing Left Alt, Left Shift, and 
Print Screen simultaneously. 
HCF_HOTKEYAVAILABLE = &H40 
The hot key can be enabled (this flag cannot be changed). 
HCF_HOTKEYSOUND = &H10 
Play a sound when the user toggles HighContrast via the hot key. 
HCF_INDICATOR = &H20 
Display an icon in the system tray while HighContrast is on. 
lpszDefaultScheme 
The name of the color scheme for HighContrast to use. 


Used by: SystemParametersInfo 
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HOSTENT Structure 


Type HOSTENT 
h_name As Long 
h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 
End Type 


Description & Usage 


The HOSTENT structure stores information about a host computer on a network. Most of the 
information in the structure is stored as a set of pointers to the actual data. 


Visual Basic-Specific Issues 


To access the data pointed to by the structure, it is necessary to use functions such as CopyMemory, 
Istrcpy, and Istrlen to copy the data into the appropriate variables. See the example for gethostbyname for 
a demonstration of how this is done. 


Data Members 


h_name 
A pointer to a null-terminated string specifying the fully-qualified domain name of the host 
computer. 
h_aliases 
A pointer to a null-terminated array of alternate domain names for the host computer. 
h_addrtype 
The address family of the base protocol used by the network. 
h_length 
The length in bytes of each address pointed to by h_addr_list. 
h_addr_list 
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A pointer to a null-terminated list of addresses for the host computer. The addresses are returned 
in network byte order. 


Used By 


gethostbyaddr, gethostbyname 


Back to the Structure list. 
Back to the Reference section. 


Last Modified: December 17, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/h/hostent.html 


http://216.26.168.92/vbapi/ref/h/hostent.html (2 of 2) [9/1/2002 5:57:19 PM] 


Windows API Guide: ICONMETRICS Structure 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








ICONMETRICS Structure 


Type ICONMETRICS 
cbhSize As Long 
iHorzSpacing As Long 
iVertSpacing As Long 
iTitleWrap As Long 
lfFont As LOGFONT 

End Type 


ICONMETRICS-type variables hold information about various icon metrics. The icon metrics specify 
information about icons in Windows, such as the font used for their titles and the spacing used to display 
them. The structure stores these metrics. 


cbSize 
The size in bytes of the structure. 
iHorzSpacing 
The horizontal space, in pixels, alloted to each arranged icon. 
iVertSpacing 
The vertical space, in pixels, alloted to each arranged icon. 
iTitleWrap 
Specifies whether the titles of icons are word-wrapped or not. Zero means the titles are not 
wrapped; a non-zero value means the titles are wrapped. 
IfFont 
Information about the logical font used to display the icon titles. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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INITTCOMMONCONTROLSEX_TYPE 
Structure 


Type INITCOMMONCONTROLSEX_TYPE 
dwSize As Long 
dwICC As Long 

End Type 


Description & Usage 


The INITCOMMONCONTROLSEX_TYPE structure tells InitCommonControlsEx which common 
control classes to register. The structure holds a combination of flags specifying which classes are 
wanted. 


Visual Basic-Specific Issues 


Officially, the name of this structure is INITCOMMONCONTROLSEX (all capitals). However, since 
Visual Basic is case-insensitive, that name conflicts with the InitCommonControlsEx API function. 
Therefore, it is necessary to give it a different name -- in this case, by appending _TYPE to the end. 


Data members. 


dwSize 
The length in bytes of the structure. 
dwICC 
A combination of the following flags specifying which common control classes to register: 
ICC_ANIMATE_CLASS 
The Animate control class. 
ICC_BAR_CLASSES 
The Toolbar, Status Bar, Trackbar, and Tooltip control classes. 
ICC_COOL_CLASSES 
The Rebar control class. 
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ICC_DATE_CLASSES 

The Date and Time Picker control class. 
ICC_HOTKEY_CLASS 

The Hot Key control class. 
ICC_INTERNET_CLASSES 

The IP Address control class. 
ICC_LISTVIEW_CLASSES 

The List View and Header control classes. 
ICC_PAGESCROLLER_CLASS 

The Pager control class. 
ICC_PROGRESS_CLASS 

The Progress Bar control class. 
ICC_TAB_CLASSES 

The Tab and Tooltip control classes. 
ICC_TREEVIEW_CLASSES 

The Tree View and Tooltip control classes. 
ICC_UPDOWN_CLASS 

The Up-Down control class. 
ICC_USEREX_CLASSES 

The ComboBoxEx control class. 
ICC_WIN95_CLASSES 


The Animate, Header, Hot Key, List View, Progress Bar, Status Bar, Tab, Tooltip, 
Toolbar, Trackbar, Tree View, and Up-Down control classes. (In other words, almost all of 


them.) 


Constant Definitions 





Const ICC_ANIMATE_CLASS = &H80 
Const ICC_BAR_CLASSES = &H4 

Const ICC_COOL_CLASSES = &H400 
Const ICC_DATE_CLASSES = &H100 
Const ICC_HOTKEY_CLASS = &H40 
Const ICC_INTERNET_CLASSES = &H800 
Const ICC_LISTVIEW_CLASSES = &H1 
Const ICC_PAGESCROLLER_CLASS = &H1000 
Const ICC_PROGRESS_CLASS = &H20 
Const ICC_TAB_CLASSES = &H8 

Const ICC_TREEVIEW_CLASSES = &H2 
Const ICC_UPDOWN_CLASS = &H10 
Const ICC_USEREX_CLASSES = &H200 
Const ICC_WIN95_CLASSES = &HFF 
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Used By 


InitCommonControlsEx 


Back to the Structure list. 
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INPUT TYPE Structure 


Type INPUT_TYPE 
dwType As Long 
x1(0 To 23) As Byte 
End Type 


Description & Usage 


The INPUT_TYPE structure holds information about an input event to be placed in the input stream. 
The input can be from the keyboard, the mouse, or some other hardware. Essentially, this structure 
merely identifies the source of an input event. 


Visual Basic-Specific Issues 


Officially, this structure is called INPUT. However, that violates the case-sensitive name spacing of 
Visual Basic because Visual Basic contains an intrinsic Input command. The Windows API Guide calls 
this structure INPUT_TYPE to avoid the naming collision. 


Also, this structure does not officially have a data member called xi. That space in the structure is 
actually a "union" of three members: mi, ki, and hi, all of which occupy the same physical space in the 
structure and of which only one can be used at any one time. Each of those actual members are the 
contents of one of the three structures discussed below physically embedded in the structure. Because, 
unlike C++, Visual Basic does not have any analogous construct, a workaround must be reached. 
Therefore, as far as Visual Basic is concerned, a byte array called xi occupies that space, into which the 
contents of one of the possible structures must be copied. See the example for SendInput for a 


demonstration. 


Data Members 


dwType 
Exactly one of the following flags specifying which type of input event this structure contains: 
INPUT_MOUSE 
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The structure identifies a mouse input event. 
INPUT_KEYBOARD 

The structure identifies a keyboard input event. 
INPUT_HARDWARE 

Windows 98: The structure identifies some other hardware input event. 

xi 

Buffer which holds the contents of a data structure, depending on the value of dwType. A 
MOUSEINPUT structure is used for mouse events, a KEYBDINPUT structure for keyboard 
events, and a HARDWAREINPUT structure for other hardware events. (See the SendInput 
example for a demonstration of using this parameter.) 


Constant Definitions 


Const INPUT_MOUSE = 0 
Const INPUT_KEYBOARD = 
Const INPUT_HARDWARE = 2 


Used By 


| 
H| 


SendInput 
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ITEMIDLIST Structure 


Type ITEMIDLIST 
mkid As SHITEMID 
End Type 


Description & Usage 

The ITEMIDLIST structure stores an item identifier which identifies something. Usually, API functions 
merely use a pointer to this structure (often called a PIDL) instead of using the structure directly. This is 
because only API function actually use the contents of the structure; regular programs don't need to use 
it. This is also because the actual size of the structure (the size of mkid) can vary widely, so API 


functions often create the structure automatically and return a pointer to it, eliminating the need for the 
program to actually process its contents in any way. 


Visual Basic-Specific Issues 


None. 


Data Members 


mkid 
Holds the item identifier data. 


Used By 


BrowseCallbackProc, BROWSEINFO, SHAddToRecentDocs, SHBrowseForFolder, 
SHELLEXECUTEINFO, SHGetFileInfo, SHGetFolderLocation, SHGetPathFromIDList, 


SHGetSpecialFolderLocation 


Go back to the alphabetical Structure listing. 
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JOB INFO_1 Structure 


Type JOB_INFO_1 
JobiId As Long 
pPrinterName As String 
pMachineName As String 
pUserName As String 
pDocument As String 
pDatatype As String 
pStatus As String 
Status As Long 
Priority As Long 
Position As Long 
TotalPages As Long 
PagesPrinted As Long 
Submitted As SYSTEMTIME 

End Type 





Description & Usage 


The JOB_INFO_1 structure holds information about a print job. The structure contains data which both 
identifies the originator of the print job and its current status in the print spooler. 


Visual Basic-Specific Issues 


None. 


Data Members 


Jobld 

The unique numeric identifier of the print job. 
pPrinterName 

The name of the printer for which the print job is spooled. 
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pMachineName 
The name of the computer which created the print job. 
pUserName 
The name of the user who owns the print job. 
pDocument 
The name of the print job (usually the document being printed). 
pDatatype 
The type of data used to record the print job. 
pStatus 
The current status of the print job. If this string is empty, the print status can instead be found in 
Status. 
Status 
If necessary, a combination of the following flags identifying the current status of the print job: 
JOB_STATUS_BLOCKED_DEVQ 
The driver cannot print the print job. 
JOB_STATUS_DELETED 
The print job has been deleted. 
JOB_STATUS_DELETING 
The print job is being deleted. 
JOB_STATUS_ERROR 
An error is associated with the print job. 
JOB_STATUS_OFFLINE 
The printer responsible for printing the print job is offline. 
JOB_STATUS_PAPEROUT 
The printer responsible for printing the print job is out of paper. 
JOB_STATUS_PAUSED 
The print job is paused. 
JOB_STATUS_PRINTED 
The print job has been printed. 
JOB_STATUS_PRINTING 
The print job is being printed. 
JOB_STATUS_RESTART 
The print job has been restarted. 
JOB_STATUS_SPOOLING 
The print job is being spooled. 
JOB_STATUS_USER_INTERVENTION 
The printer responsible for printing the print job has suffered an error requiring the user to 
do something. 
Priority 
A value between 1 and 99 inclusive specifying the priority of the print job (99 being highest). One 
of the following flags can be used as well: 
DEF_PRIORITY 
Default priority. 
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MIN_PRIORITY 
Minimum priority. 
MAX_PRIORITY 
Maximum priority. 
Position 
The current position of the print job in the print queue. 
TotalPages 
The total number of pages which make up the print job, if available. 
PagesPrinted 
The number of pages of the print job which have already been printed, if available. 
Submitted 
The date and time when the document was spooled into the queue. This time is in Universal 
Coordinated Time (UTC, a.k.a. Greenwich Mean Time, or GMT) instead of in the system's local 
time zone time. 


Constant Definitions 


Const JOB _STATUS_BLOCKED_DEVQ = &H200 
Const JOB_STATUS_DELETED = &H100 

Const JOB_STATUS_DELETING = &H4 

Const JOB_STATUS_ERROR = &H2 

Const JOB_STATUS_OFFLINE = &H20 

Const JOB_STATUS_PAPEROUT = &H40 

Const JOB_STATUS_PAUSED = &H1 

Const JOB_STATUS_PRINTED = &H80 

Const JOB_STATUS_PRINTING = &H10 

Const JOB_STATUS_RESTART = &H800 

Const JOB_STATUS_SPOOLING = &H8 

Const JOB_STATUS_USER_INTERVENTION = &H400 
Const DEF PRIORITY = 1 

Const MIN PRIORITY 
Const MAX PRIORITY 


Used By 











II 
H| 


99 


EnumJobs 


Go back to the Structure listing. 
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JOB_INFO 2 Structure 


Type JOB_INFO_2 
JobiId As Long 
pPrinterName As String 
pMachineName As String 
pUserName As String 
pDocument As String 
pNotifyName As String 
pDatatype As String 
pPrintProcessor As String 
pParameters As String 
pDriverName As String 
pDevMode As DEVMODE 
pStatus As String 
pSecurityDescriptor As SECURITY DESCRIPTOR 
Status As Long 
Priority As Long 
Position As Long 
StartTime As Long 
UntilTime As Long 
TotalPages As Long 
Size As Long 
Submitted As SYSTEMTIME 
Time As Long 
PagesPrinted As Long 

End Type 








Description & Usage 


The JOB_INFO_2 structure holds information about a print job. The structure contains data which both 
identifies the originator of the print job and its current status in the print spooler. 


Visual Basic-Specific Issues 
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None. 


Data Members 


Jobld 

The unique numeric identifier of the print job. 
pPrinterName 

The name of the printer for which the print job is spooled. 
pMachineName 

The name of the computer which created the print job. 
pUserName 

The name of the user who owns the print job. 
pDocument 

The name of the print job (usually the document being printed). 
pNotifyName 

The name of the user who should be notified when the print job is complete or when an error 

occurs while printing. 
pDatatype 

The type of data used to record the print job. 
pPrintProcessor 

The name of the print processor to be used to print the print job. 
pParameters 


The parameters of the print processor. 
pDriverName 
The name of the printer driver to be used to process the print job. 
pDevMode 
Device initialization and environment data for the printer driver. 
pStatus 
The current status of the print job. If this string is empty, the print status can instead be found in 
Status. 
pSecurityDescriptor 
Reserved -- do not use. 
Status 
If necessary, a combination of the following flags identifying the current status of the print job: 
JOB_STATUS_BLOCKED_DEVQ 
The driver cannot print the print job. 
JOB_STATUS_DELETED 
The print job has been deleted. 
JOB_STATUS_DELETING 
The print job is being deleted. 
JOB_STATUS_ERROR 
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An error is associated with the print job. 
JOB_STATUS_OFFLINE 
The printer responsible for printing the print job is offline. 
JOB_STATUS_PAPEROUT 
The printer responsible for printing the print job is out of paper. 
JOB_STATUS_PAUSED 
The print job is paused. 
JOB_STATUS_PRINTED 
The print job has been printed. 
JOB_STATUS_PRINTING 
The print job is being printed. 
JOB_STATUS_RESTART 
The print job has been restarted. 
JOB_STATUS_SPOOLING 
The print job is being spooled. 
JOB_STATUS_USER_INTERVENTION 
The printer responsible for printing the print job has suffered an error requiring the user to 
do something. 
Priority 
A value between 1 and 99 inclusive specifying the priority of the print job (99 being highest). One 
of the following flags can be used as well: 
DEF_PRIORITY 
Default priority. 
MIN_PRIORITY 
Minimum priority. 
MAX_PRIORITY 
Maximum priority. 
Position 
The current position of the print job in the print queue. 
StartTime 
The earliest time that the print job can be printed (specified as number of minutes after midnight 
UTC (Universal Coordinated Time, a.k.a. Greenwich Mean Time or GMT). 
UntilTime 
The latest time that the print job can be printed (specified as number of minutes after midnight 
UTC (Universal Coordinated Time, a.k.a. Greenwich Mean Time or GMT). 
TotalPages 
The total number of pages which make up the print job, if available. 
Size 
The size in bytes of the print job. 
Submitted 
The date and time when the document was spooled into the queue. This time is in Universal 
Coordinated Time (UTC, a.k.a. Greenwich Mean Time, or GMT) instead of in the system's local 
time zone time. 
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Time 

The total amount of time, in seconds, since the print job has begun printing. 
PagesPrinted 

The number of pages of the print job which have already been printed, if available. 


Constant Definitions 


Const JOB_STATUS_BLOCKED_DEVQ = &H200 
Const JOB_STATUS_DELETED = &H100 

Const JOB_STATUS_DELETING = &H4 

Const JOB _STATUS_ERROR = &H2 

Const JOB_STATUS_OFFLINE = &H20 

Const JOB_STATUS_PAPEROUT = &H40 

Const JOB_STATUS PAUSED = &H1 

Const JOB_STATUS_PRINTED = &H80 

Const JOB_STATUS_PRINTING = &H10 

Const JOB_STATUS_SPOOLING = &H8 

Const JOB_STATUS_USER_INTERVENTION = &H400 
Const DEF PRIORITY 
Const MIN PRIORITY 
Const MAX PRIORITY = 


Used By 











II 
orr] 


EnumJobs 
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JOYCAPS Structure 


Type JOYCAPS 

wMid As Integer 

wPid As Integer 
szPname As String * 32 
wxXmin As Long 

wXmax As Long 

wYmin As Long 

wYmax As Long 

wZmin As Long 








wZmax As Long 
wNumButtons As Long 
wPeriodMin As Long 
wPeriodMax As Long 
wRmin As Long 
wRmax As Long 
wUmin As Long 
wUmax As Long 
wVmin As Long 








wVmax As Long 

wMaxAxes As Long 

wNumAxes As Long 

wMaxButtons As Long 

szRegKey As String * 32 

SZOEMVxD As String * 240 
End Type 


JOYCAPS-type variables hold information about a joystick (not to be confused with the current position 
of the joystick). Namely, this structure holds the axes' ranges and the number of buttons the joystick has. 


wMid 

The manufacturer identifier of the device. 
wPid 

The product identifier of the device. 
szPname 
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The name of the joystick's device driver. 
wxXmin 
The minimum x-axis coordinate value. 
wXmax 
The maximum x-axis coordinate value. 
wYmin 
The minimum y-axis coordinate value. 
wYmax 
The maximum y-axis coordinate value. 
wZmin 
The minimum z-axis coordinate value. 
wZmax 
The maximum z-axis coordinate value. 
wNumButtons 
The number of buttons on the joystick. 
wPeriodMin 
The minimum supported polling frequency. 
wPeriodMax 
The maximum supported polling frequency. 
wRmin 
The minimum r-axis (rudder, fourth axis) coordinate value. 
wRmax 
The maximum r-axis (rudder, fourth axis) coordinate value. 
wUmin 
The minimum u-axis (fifth axis) coordinate value. 
wUmax 
The maximum u-axis (fifth axis) coordinate value. 
wVmin 
The minimum v-axis (sixth axis) coordinate value. 
wVmax 
The maximum v-axis (sixth axis) coordinate value. 
wCaps 
Zero or more flags specifying various capabilities or characteristics of the joystick: 
JOYCAPS_HASPOV = &H10 
Joystick provides point-of-view information. 
JOYCAPS_HASR = &H2 
Joystick provides rudder (fourth axis) information. 
JOYCAPS_HASU = &H4 
Joystick provides u-axis (fifth axis) information. 
JOYCAPS_HASV = &H8 
Joystick provides v-axis (sixth axis) information. 
JOYCAPS_HASZ = &H1 
Joystick provides z-axis information. 
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JOYCAPS_ POV4DIR = &H20 
Joystick's point-of-view indicator supports discrete values (e.g., centered, left, right, up, 
down, etc.). 
JOYCAPS_POVCTS = &H40 
Joystick's point-of-view indicator supports continuous degree bearings. 
wMaxAxes 
The maximum number of axes supported by the joystick. 
wNumAxes 
The number of axes currently used by the joystick. 
wMaxButtons 
The maximum number of buttons supported by the joystick. 
szRegKey 
The registry key that holds the joystick's information. 
SZOEMVxD 
Identifies the original equipment manufacturer (OEM) of the joystick. 


Used by: joyGetDevCaps 
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JOYINFO Structure 


Type JOYINFO 
wxpos As Long 
wYpos As Long 
w4Z4pos As Long 
wButtons As Long 
End Type 


JOYINFO-type variables hold the current position of a joystick. This structure can store the positions of 
the x, y, and z axes, as well as the buttons pushed. Note that this structure can only receive information 
about buttons 1 through 4 on the joystick -- if there are more, they are ignored. 


wXpos 
The current x-axis coordinate. 
wYpos 
The current y-axis coordinate. 
wZpos 
The current z-axis coordinate. 
wButtons 
Zero or more of the following flags, specifying which buttons are being depressed: 
JOY_BUTTONI1 = &H1 
Button #1 is depressed. 
JOY_BUTTON2 = &H2 
Button #2 is depressed. 
JOY_BUTTON3 = &H4 
Button #3 is depressed. 
JOY_BUTTON4 = &H8 
Button #4 is depressed. 


Used by: joyGetPos 


Go back to the alphabetical Structure listing. 
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KEYBDINPUT 


Type KEYBDINPUT 
wVk As Integer 
wscan As Integer 
dwFlags As Long 
time As Long 
dwExtraInfo As Long 
End Type 


Description & Usage 


The KEYBDINPUT structure holds information about a keyboard input event. The various data 
members describe the exact nature of the keyboard input event. Windows 2000: This structure can also 
be used to synthisized keyboard input generated by a hardware device imitating the keyboard. 


Visual Basic-Specific Issues 


None. 


Data Members 


wVk 
The virtual-key code of the key to simulate pressing or releasing. If dwFlags contains the 
KEYEVENTF_UNICODE tag, this must be 0. 
wScan 
If dwFlags contains the KEYEVENTF_UNICODE flag, this specifies the hardware scan code of 
the Unicode character key to simulate pressing or releasing. If that flag is not used, this must be 0. 
dwFlags 
A combination of the following flags specifying what kind of keyboard input to synthesize: 
KEYEVENTF_EXTENDEDKEY 
Prefix the scan code with a prefix byte having the value & HEO. 
KEYEVENTF_KEYUP 
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The key specified in bVk is being released. If this flag is not specified, the key is being 
pressed. 

KEYEVENTF_UNICODE 
Windows 2000: Use a Unicode character key generated by a non-keyboard hardware input 
which is imitating keyboard input. 


time 
The time stamp of the keyboard input event, in milliseconds. If 0, the system creates a time 
stamp by default. 

dwExtralnfo 


An additional 32-bit value associated with the keyboard event. 


Constant Definitions 


Const KEYEVENTF_EXTENDEDKEY = &H1 
Const KEYEVENTF_KEYUP = &H2 
Const KEYEVENTF_UNICODE = &H4 


Used By 


INPUT_TYPE 
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LARGE_INTEGER Structure 


Type LARGE_INTEGER 
LowPart As Long 
HighPart As Long 

End Type 


Description & Usage 


The LARGE_INTEGER structure stores a 64-bit signed integer. Unsigned integers range in value from - 
263 to 263 - 1. This structure is defined primarily for languages (such as Visual Basic but including many 
others) which have no intrinsic support for 64-bit signed integers. The structure splits the value into two 
32-bit halves: a high-order half and a low-order half. If the programming language you use does support 
64-bit signed integers, you can replace the two data members of this structure with a single value (or use 
that data type instead of the structure altogether). 


Visual Basic-Specific Issues 


There is a way to use a variable of the Currency data type to represent a 64-bit integer. For more 
information, read the article "Faking 64-bit Integers." 


Data Members 


LowPart 

The 32-bit low-order half of the full 64-bit signed integer. 
HighPart 

The 32-bit high-order half of the full 64-bit signed integer. 


Used By 


QueryPerformanceCounter, QueryPerformanceFrequency 
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LOGFONT Structure 


Type LOGFONT 
lfHeight As Long 
1lfWidth As Long 
lfEscapement As Long 
lfOrientation As Long 
lfWeight As Long 
lfItalic As Byte 
lfUnderline As Byte 
1fStrikeOut As Byte 
1fCharSet As Byte 
l1fOutPrecision As Byte 
1fClipPrecision As Byte 
lfQuality As Byte 
1fPitchAndFamily As Byte 
lfFaceName As String * 32 

End Type 


Description & Usage 


The LOGFONT structure holds information about a logical font. The various members of the structure 
specify properties of the logical font. 


Visual Basic-Specific Issues 
None. 
Data Members 


lfHeight 
The height of the font's character cell, in logical units (also known as the em height). If positive, 
the font mapper converts this value directly into device units and matches it with the cell height of 
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the possible fonts. If 0, the font mapper uses a default character height. If negative, the font 
mapper converts the absolute value into device units and matches it with the character height of 
the possible fonts. 
[fWidth 
The average width of the font's characters. If 0, the font mapper tries to determine the best value. 
IfEscapement 
The angle between the font's baseline and escapement vectors, in units of !/,) degrees. Windows 


95, 98: This must be equal to /fOrientation. 
lfOrientation 
The angle between the font's baseline and the device's x-axis, in units of !/ 19 degrees. Windows 


95, 98: This must be equal to /[fEscapement. 
lfWeight 

One of the following flags specifying the boldness (weight) of the font: 
FW_DONTCARE 

Default weight. 
FW_THIN 

Thin weight. 
FW_EXTRALIGHT 

Extra-light weight. 
FW_ULTRALIGHT 

Same as FW_EXTRALIGHT. 
FW_LIGHT 

Light weight. 
FW_NORMAL 

Normal weight. 
FW_REGULAR 

Same as FW_NORMAL. 
FW_MEDIUM 

Medium weight. 
FW_SEMIBOLD 

Semi-bold weight. 
FW_DEMIBOLD 

Same As FW_SEMIBOLD. 
FW_BOLD 

Bold weight. 
FW_EXTRABOLD 

Extra-bold weight. 
FW_ULTRABOLD 

Same as FW_EXTRABOLD. 
FW_HEAVY 

Heavy weight. 
FW_BLACK 

Same as FW_HEAVY. 
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[fItalic 
A non-zero value if the font is italicized, 0 if not. 
lfUnderline 
A non-zero value if the font is underlined, O if not. 
LfStrikeOut 
A non-zero value if the font is striked out, 0 if not. 
lfCharSet 
Exactly one of the following flags specifying the character set of the font: 
ANSI_CHARSET 
ANSI character set. 
ARABIC _CHARSET 
Windows NT, 2000: Arabic character set. 
BALTIC_CHARSET 
Windows 95, 98: Baltic character set. 
CHINESEBIGS_CHARSET 
Chinese Big 5 character set. 
DEFAULT_CHARSET 
Default character set. 
EASTEUROPE_CHARSET 
Windows 95, 98: Eastern European character set. 
GB2312_CHARSET 
GB2312 character set. 
GREEK_CHARSET 
Windows 95, 98: Greek character set. 
HANGEUL_CHARSET 
HANDEUL character set. 
HEBREW_CHARSET 
Windows NT, 2000: Hebrew character set. 
JOHAB_CHARSET 
Windows 95, 98: Johab character set. 
MAC_CHARSET 
Windows 95, 98: Mac character set. 
OEM_CHARSET 
Original equipment manufacturer (OEM) character set. 
RUSSIAN_CHARSET 
Windows 95, 98: Russian character set. 
SHIFTJIS_CHARSET 
ShiftJis character set. 
SYMBOL_CHARSET 
Symbol character set. 
THAI_CHARSET 
Windows NT, 2000: Thai character set. 
TURKISH_CHARSET 
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Windows 95, 98: Turkish character set. 
lfOutPrecision 
Exactly one of the following flags specifying the desired precision (closeness of the match) 
between the logical font ideally described by the structure and the actual logical font. This value is 
used by the font mapper to produce the logical font. 
OUT_DEFAULT_PRECIS 
The default font mapping behavior. 
OUT_DEVICE_PRECIS 
Choose a device font if there are multiple fonts in the system with the same name. 
OUT_OUTLINE_PRECIS 
Windows NT, 2000: Choose a TrueType or other outline-based font. 
OUT_RASTER_PRECIS 
Choose a raster font if there are multiple fonts in the system with the same name. 
OUT_STRING_PRECIS 
Raster font (used for enumeration only). 
OUT_STROKE_PRECIS 
Windows 95, 98: Vector font (used for enumeration only). Windows NT, 2000: 
TrueType, outline-based, or vector font (used for enumeration only). 
OUT_TT_ONLY_PRECIS 
Choose only a TrueType font. 
OUT_TT_PRECIS 
Choose a TrueType font if there are multiple fonts in the system with the same name. 
IfClipPrecision 
Exactly one of the following flags specifying the clipping precision to use when the font's 
characters must be clipped: 
CLIP_DEFAULT_PRECIS 
The default clipping behavior. 
CLIP_LEMBEDDED 
This flag must be set for an embedded read-only font. 
CLIP_LH_ANGLES 
The direction of any rotations is determined by the coordinate system (or else all rotations 
are counterclockwise). 
CLIP_STROKE_PRECIS 
Raster, vector, or TrueType font (used for enumeration only). 
lfQuality 
Exactly one of the following flags specifying the output quality of the logical font as compared to 
the ideal font: 
ANTIALIASED_QUALITY 
Windows 95, 98, NT 4.0 or later, 2000: The font is always antialiased if possible. 
DEFAULT_QUALITY 
The default quality: the appearance of the font does not matter. 
DRAFT_QUALITY 
The appearance of the font is less important then in PROOF_QUALITY. 
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NONANTIALIASED_ QUALITY 
Windows 95, 98, NT 4.0 or later, 2000: The font is never antialiased. 
PROOF_QUALITY 
The quality of the appearance of the font is more important than exactly matching the 
specified font attributes. 
[fPitchAndFamily 
A bitwise OR combination of exactly one *_PITCH flag specifying the pitch of the font and 
exactly one FF_* flag specifying the font face family of the font: 
DEFAULT_PITCH 
The default pitch. 
FIXED_PITCH 
Fixed pitch. 
VARIABLE_PITCH 
Variable pitch. 
FF_DECORATIVE 
Showy, decorative font face. 
FF_DONTCARE 
Do not care about the font face. 
FF_MODERN 
Modern font face (monospaced, sans serif font). 
FF_ROMAN 
Roman font face (proportional-width, serif font). 
FF_SCRIPT 
Script font face which imitates script handwriting. 
FF_SWISS 
Swiss font face (proportional-width, sans serif font). 
lfFaceName 
The name of the font face to use. This string must be terminated with a null character. 


Constant Definitions 


Const FW_DONTCARE = 0 
Const FW_THIN = 100 

Const FW_EXTRALIGHT 200 
Const FW_ULTRALIGHT = 200 
Const FW_LIGHT = 300 
Const FW_NORMAL = 400 
Const FW_REGULAR = 400 
Const FW_MEDIUM = 500 
Const FW_SEMIBOLD = 600 
Const FW_DEMIBOLD = 600 
Const FW_BOLD = 700 
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Const FW_EXTRABOLD = 800 

Const FW_ULTRABOLD 800 

Const FW_HEAVY = 900 

Const FW_BLACK = 900 

Const ANSI_CHARSET = 0 

Const ARABIC_CHARSET = 178 
Const BALTIC_CHARSET = 186 
Const CHINESEBIG5 CHARSET = 136 
Const DEFAULT_CHARSET = 1 
Const EASTEUROPE_CHARSET = 238 
Const GB2312 CHARSET = 134 
Const GREEK _CHARSET = 161 
Const HANGEUL_CHARSET = 129 
Const HEBREW _CHARSET = 177 
Const JOHAB CHARSET = 130 
Const MAC_CHARSET ede 

Const OEM _CHARSET = 255 

Const RUSSIAN _CHARSET = 204 
Const SHIFTJIS_CHARSET = 128 
Const SYMBOL CHARSET = 
Const THAI _CHARSET = 22 


2 
2 








Const TURKISH_CHARSET = 162 
Const OUT_DEFAULT_PRECIS = 0 
Const OUT_DEVICE_PRECIS = 5 
Const OUT_OUTLINE_PRECIS = 8 
Const OUT_RASTER_PRECIS = 6 
Const OUT_STRING_PRECIS = 1 
Const OUT_STROKE_PRECIS = 3 
Const OUT_TT_ONLY_PRECIS = 7 
Const OUT_TT_PRECIS = 4 


Const CLIP_DEFAULT_PRECIS = 0 
Const CLIP_KEMBEDDED = 128 
Const CLIP_LH_ANGLES = 16 
Const CLIP_STROKE_PRECIS = 2 
Const ANTIALIASED QUALITY = 4 
Const DEFAULT_QUALITY = 0 
Const DRAFT QUALITY = 1 

Const NONANTIALIASED_ QUALITY = 3 
Const PROOF_QUALITY = 2 

Const DEFAULT_PITCH = 0 

Const FIXED PITCH = 1 

Const VARIABLE PITCH = 2 
Const FF_DECORATIVE = 80 
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Const FF_DONTCARE = 0 
Const FF_MODERN = 48 
Const FF_ROMAN = 16 
Const FF_SCRIPT = 64 
Const FF_SWISS = 32 


Used By 


CHOOSEFONT_TYPE, CreateFontIndirect, EnumFontFamiliesEx, ENUMLOGFONT, 
ENUMLOGFONTEX, ICONMETRICS, NONCLIENTMETRICS, SystemParametersInfo 


Go back to the Structure listing. 
Go back to the Reference section index. 
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LOGPEN Structure 


Type LOGPEN 
lopnStyle As Long 
lopnWidth As POINT TYPE 
lopnColor As Long 

End Type 





Description & Usage 


The LOGPEN structure holds information used to identify a logical pen. The pen described by the 
structure is always shaped like a square. 


Visual Basic-Specific Issues 


None. 


Data Members 


lopnStyle 
One of the following flags specifying the style of the pen: 
PS_SOLID 
The pen is solid. 
PS_DASH 
The pen is dashed. The width must be less than or equal to one. 
PS_DOT 
The pen is dotted. The width must be less than or equal to one. 
PS_DASHDOT 
The pen has alternating dashes and dots. The width must be less than or equal to one. 
PS_DASHDOTDOT 
The pen has alternating dashes followed by two dots. The width must be less than or equal 
to one. 
PS_NULL 
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The pen is invisible. 
PS_INSIDEFRAME 
The pen is solid. Whenever a drawing function draws a figure inside a bounding rectangle, 
the dimensions of the figure are shrunk so that the entire figure, including the width of the 
pen, fits entirely within the bounding rectangle. 
lopnWidth 
The .x member of the structure identifies the width of the pen. A width of zero produces a one- 
pixel-wide pen no matter what. The .y member of the structure is ignored. 
lopnColor 
The RGB value of the color of the pen. 


Constant Definitions 


Const PS_SOLID = 0 

Const -PS DASH = 1 

Const PS_DOT = 2 

Const PS_DASHDOT = 3 
Const PS_DASHDOTDOT = 4 
Const PS_NULL = 5 

Const PS_INSIDEFRAME = 6 


Used By 





CreatePenIndirect 


Go back to the alphabetical Structure listing. 
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MEMORYSTATUS Structure 


Type MEMORYSTATUS 
dwLength As Long 
dwMemoryLoad As Long 
dwTotalPhys As Long 
dwAvailPhys As Long 
dwTotalPageFile As Long 
dwAvailPageFile As Long 
dwTotalVirtual As Long 
dwAvailVirtual As Long 

End Type 


Description & Usage 


The MEMORYSTATUS structure holds information about the computer's memory. The structure stores 
the amounts of total and available physical memory and virtual memory. 


Visual Basic-Specific Issues 


None. 


Data Members 


dwLength 
The size in bytes of the structure. 
dwMemoryLoad 
Windows 95, 98, NT: The percentage of approximately the last 1000 pages of physical memory 
that is in use. Windows 2000: The percentage of total physical memory in use. 
dwTotalPhys 
The number of bytes of total physical memory. 
dwAvailPhys 
The number of bytes of available physical memory. 
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dwTotalPageFile 
The largest possible size, in bytes, of the paging file. This is not necessarily the current size of the 
paging file. 
dwAvailPageFile 
The amount of space, in bytes, currently available in the paging file. 
dwTotalVirtual 
The number of bytes of total virtual memory. 
dwAvailVirtual 
The number of bytes of available virtual memory. 


Used By 


GlobalMemoryStatus 


Back to the Structure list. 
Back to the Reference section. 
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MEMORYSTATUSEX Structure 


Type MEMORYSTATUSEX 
dwLength As Long 
dwMemoryLoad As Long 
ullTotalPhys As ULARGE INTEGER 


ullAvailPhys As ULARGE INTEGER 

ullTotalPageFile As ULARGE INTEGER 

ullAvailPageFile As ULARGE INTEGER 

ullTotalVirtual As ULARGE INTEGER 

ullAvailVirtual As ULARGE INTEGER 

ullAvailExtendedVirtual As ULARGE INTEGER 
End Type 























Description & Usage 


The MEMORYSTATUSEX structure holds information about the computer's memory. The structure 
stores the amounts of total and available physical memory and virtual memory. All values for amounts of 
memory are stored as 64-bit integers. 


Visual Basic-Specific Issues 


None. 


Data Members 


dwLength 

The size in bytes of the structure. 
dwMemoryLoad 

The percentage of total physical memory in use. 
ullTotalPhys 

The number of bytes of total physical memory. 
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ullAvailPhys 
The number of bytes of available physical memory. 
ullTotalPageFile 
The largest possible size, in bytes, of the paging file. This is not necessarily the current size of the 
paging file. 
ullAvailPageFile 
The amount of space, in bytes, currently available in the paging file. 
ullTotalVirtual 
The number of bytes of total virtual memory. 
ullAvailVirtual 
The number of bytes of available virtual memory. 
ullAvailExtendedVirtual 
The number of bytes of unreserved and uncommitted memory in the extended portion of virtual 
memory. 


Used By 


GlobalMemoryStatusEx 


Back to the Structure list. 
Back to the Reference section. 
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MENUITEMINFO Structure 


Type MENUITEMINFO 
cbSize As Long 
fMask As Long 
fType As Long 
fState As Long 
wID As Long 
hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwitemData As Long 
dwTypeData As String 
cch As Long 

End Type 


Description & Usage 


The MENUITEMINFO structure holds information that describes a menu item. This description 
includes the text of the item, its state (enabled, gray, etc.), and other things relating to its appearance. 


Visual Basic-Specific Issues 


If you need to set dwTypeData to a handle to a bitmap, a slight modification to the above structure 


definition must be made. Change the type of the dwTypeData data member from "As String" to "As 
Long". With that change made, it can now be set to a bitmap handle. 





Data Members 


cbSize 
The size, in bytes, of the structure. 


{Mask 


A combination of the following flags specifying which parts of the structure to use. Any other 
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fType 


data members not specified by a flag will be ignored. 
MIIM_STATE 

Use the fState data member. 
MIIM_ID 

Use the w/D data member. 
MIIM_SUBMENU 

Use the hSubMenu data member. 
MIIM_CHECKMARKS 

Use the hbmpChecked and hbmpUnchecked data members. 
MIIM_DATA 

Use the dwltemData data member. 
MIIM_TYPE 

Use the dwTypeData and cch data members. 


A combination of the following flags specifying the type of menu item the structure describes: 
MFT_BITMAP 
The menu item is displayed using a bitmap. dwTypeData is a handle to the bitmap to use, 
and cch is ignored. This flag cannot be combined with MFT_SEPARATOR or 
MFT_STRING. 
MFT_MENUBARBREAK 
Place this item on a new row (for a menu bar) or column (for a drop-down menu, 
submenu, or context menu). If starting a new column, separate the two columns by a 
vertical line. 
MFT_MENUBREAK 
Same as MFT_MENUBARBREAK, but do not draw a line separating the two columns. 
MFT_OWNERDRAW 
Make the menu item owner-drawn. This makes the owning window completely 
responsible for drawing the menu item whenever necessary. 
MFT_RADIOCHECK 
When checked, place a radio-button mark instead of a check mark next to the menu item. 
This signifies a radio-button-type menu item. 
MFT_RIGHTJUSTIFY 
For menu bars only, right-justify this item and all other items after it. 
MFT_RIGHTORDER 
Windows 95, 98, 2000: The menus cascade from right to left, supporting languages that 
are read from right to left. 
MFT_SEPARATOR 
The menu item is a separator bar. dwTypeData and cch are ignored. This flag cannot be 
combined with MFT_BITMAP or MFT_STRING. 
MFT_STRING 
The menu item is represented by a text string (which may or may not be checked or have a 
submenu attached). dwTypeData is the string to display for the menu item, and cch is the 
string's length. This flag cannot be combined with MFT_BITMAP or MFT_SEPARATOR. 
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fState 
A combination of the following flags specifying the menu item's current state: 
MFS_CHECKED 
A check mark (or radio-button mark) appears next to the menu item. 
MFS_DEFAULT 
This item is the default selection for the menu. 
MFS_DISABLED 
The menu item is disabled. Although it is displayed normally, the user cannot select it. 
MFS_ENABLED 
The menu item is enabled. 
MFS_GRAYED 
The menu item is grayed out. The user cannot select it. 
MFS_HILITE 
The menu item currently has the selection highlight. 
MFS_UNCHECKED 
No check mark (or radio-button mark) appears next to the menu item. 
MFS_UNHILITE 
The menu item does not currently have the selection highlight. 
wID 
The unique 16-bit identifier of the menu item. 
hSubMenu 
A handle to the submenu that opens when the menu item is selected. 
hbmpChecked 


A handle to the bitmap to display next to the menu item when the item is checked. The bitmap's 
colors will be inverted when the selection highlight moves over the item. 

hbmp Unchecked 
A handle to the bitmap to display next to the menu item when the item is not checked. The 
bitmap's colors will be inverted when the selection highlight moves over the item. 

dwItemData 
Program-defined information to associate with the menu item. This information is not used by 
Windows. 

dwTypeData 
If fType contains MFT_STRING, this is the string to display for the menu item. If fType contains 
MFT_BITMAP, this is a handle to the bitmap used to represent the menu item. 

cch 
If dwTypeData is a string, this is the number of characters in that string. 


Constant Definitions 


Const MIIM_ STATE = &H1 
Const MIIM_ID = &H2 
Const MIIM SUBMENU = &H4 
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Const MIIM_CHECKMARKS = &H8 
Const MIIM_DATA = &H20 

Const MIIM_TYPE = &H10 

Const MFT BITMAP = &H4 

Const MFT _MENUBARBREAK = &H20 
Const MET _MENUBREAK &H40 
Const MFT_OWNERDRAW = &H100 
Const MFT_RADIOCHECK = &H200 
Const MFT_RIGHTJUSTIFY = &H4000 
Const MFT _RIGHTORDER = &H2000 
Const MFT_SEPARATOR = &H800 
Const MFT_STRING = &HO 

Const MFS_ CHECKED = &H8 

Const MEFS DEFAULT &H1000 
Const MFS_ DISABLED = &H2 
Const MFS_ENABLED = &HO 

Const MFS_GRAYED = &H1 

Const MFS_HILITE = &H80 

Const MEFS UNCHECKED = &H0O 
Const MFS_UNHILITE = &HO 


Used By 


GetMenultemInfo, InsertMenultem, SetMenultemInfo 





Back to the Structure list. 
Back to the Reference section. 
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MINIMIZEDMETRICS Structure 


Type MINIMIZEDMETRICS 
cbSize As Long 
iWidth As Long 
iHorzGap As Long 
iVertGap As Long 
iArrange As Long 

End Type 


MINIMIZEDMETRICS-type variable hold information about the metrics of minimized windows. The 
metrics of minimized windows specify various properties that Windows uses to work with all minimized 
windows. The structure stores these metrics. 


cbSize 
The size in bytes of the structure. 
iWidth 
The width in pixels of minimized windows. 
iHorzGap 
The horizontal space in pixels between arranged minimized windows. 
iVertGap 
The vertical space in pixels between arranged minimized windows. 
iArrange 
Exactly two of the following flags specifying the method used to display minimized windows. 
One flag specifies a starting position for the minimized icons and the other specifies the direction 
in which new ones are added: 
ARW_BOTTOMLEFT = 0 
Start placing the icons in the bottom-left corner of the screen. 
ARW_BOTTOMRIGHT = 1 
Start placing the icons in the bottom-right corner of the screen. 
ARW_DOWN = 4 
Add new icons below existing ones. 


ARW_HIDE = 8 
Do not place the icons anywhere on the screen (i.e., hide them). 
ARW_LEFT = 0 


Add new icons to the left of existing ones. 
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ARW_RIGHT = 4 

Add new icons to the right of existing ones. 
ARW_STARTRIGHT = 1 

Same as ARW_BOTTOMRIGHT. 
ARW_STARTTOP = 2 

Same as ARW_TOPLEFT. 
ARW_TOPLEFT = 2 

Start placing the icons in the top-left corner of the screen. 
ARW_TOPRIGHT = 3 

Start placing the icons in the top-right corner of the screen. 
ARW_UP =0 

Add new icons above existing ones. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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MOUSEINPUT Structure 


Type MOUSEINPUT 
dx As Long 
dy As Long 
mouseData As Long 
dwFlags As Long 
time As Long 
dwExtraInfo As Long 
End Type 


Description & Usage 


The MOUSEINPUT structure holds information about a mouse input event. The various data members 
identify the nature of the input. 


Visual Basic-Specific Issues 


None. 


Data Members 


dx 
Specifies either the x-coordinate of absolute mouse movement or the amount of relative 
movement along the x-axis. For relative motion, positive values move right and negative values 
move left. 

dy 
Specifies either the y-coordinate of absolute mouse movement or the amount of relative 
movement along the y-axis. For relative motion, positive values move down and negative values 
move up. 

mouseData 
Windows NT, 2000: If dwFlags contains MOUSEEVENTF_WHEEL, this specifies the amount 
of wheel movement, in integer multiples of WHEEL_DATA. Positive values mean forward 
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(away) rotation, and negative values mean backwards (toward) rotation. Windows 2000: If 
dwFlags contains either MOUSEEVENTF_XDOWN or MOUSEEVENTF_XUP, this is a 
combination of the following flags specifying which X buttons have been pressed or released: 
XBUTTONI 

The first X button was pressed or released. 
XBUTTON2 

The second X button was pressed or released. 


dwFlags 


time 


A combination of the following flags specifying which mouse input information the event 
describes. Only specify button status information for those which have changed. Note that scroll 
wheel movement and X button status cannot be simultaneously specified because they both use 
the mouseData data member. 
MOUSEEVENTF_ABSOLUTE 
The dx and dy data members contain absolute mouse coordinates. In the coordinate system 
used by the function, the screen's upper-left corner has coordinates (0,0) and the lower- 
right corner has coordinates (65535,65535), regardless of the actual screen size. If this flag 
is not set, dx and dy contain relative coordinates, whose actual amount of movement 
depends on the current mouse speed and acceleration settings. 
MOUSEEVENTF_LEFTDOWN 
The left button was pressed. 
MOUSEEVENTF_LEFTUP 
The left button was released. 
MOUSEEVENTF_MIDDLEDOWN 
The middle button was pressed. 
MOUSEEVENTF_MIDDLEUP 
The middle button was released. 
MOUSEEVENTF_MOVE 
The mouse moved. The dx and dy data members specify the amount or location of the 
movement. 
MOUSEEVENTF_RIGHTDOWN 
The right button was pressed. 
MOUSEEVENTF_RIGHTUP 
The right button was released. 
MOUSEEVENTF_WHEEL 
Windows NT, 2000: The scroll wheel has moved. The dwData data member specifies the 
amount of movement. 
MOUSEEVENTF_XDOWN 
Windows 2000: An X button was pressed. The dwData parameter identifies which X 
buttons. 
MOUSEEVENTF_XUP 
Windows 2000: An X button was released. The dwData parameter identifies which X 
buttons. 
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The time stamp of the mouse input event, in milliseconds. If this is 0, the system provides a time 
stamp. 

dwExtralnfo 
An additional 32-bit value associated with the mouse event. 


Constant Definitions 


Const M 
Const M 
Const M 


OUSEEVENTF_ABSOLUTE = &H8000 
OUSEEVENTF_LEFTDOWN = &H2 
OUSEEVENTF_LEFTUP = &H4 
Const MOUSEEVENTF_MIDDLEDOWN = &H20 
Const MOUSEEVENTF_MIDDLEUP = &H40 
Const MOUSEEVENTF_MOVE = &H1 
Const MOUSEEVENTF_RIGHTDOWN = &H8 
Const MOUSEEVENTF_RIGHTUP = &H10 
Const MOUSEEVENTF_WHEEL = &H80 
Const MOUSEEVENTF_XDOWN = &H100 
Const MOUSEEVENTF_XUP = &H200 
Const WHEEL DELTA = 120 
Const XBUTTONI = &H1 
Const XBUTTON2 = &H2 


Used By 


INPUT_TYPE 

















Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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MOUSEKEYS Structure 


Type MOUSEKEYS 
cbhSize As Long 
dwFlags As Long 
iMaxSpeed As Long 
iTimeToMaxSpeed As Long 
iCtrlSpeed As Long 
dwReservedl As Long 
dwReserved2 As Long 

End Type 


MOUSEKEYS-type variables store information about the MouseKeys accessibility feature. MouseKeys 
allows the mouse cursor to be moved by the numeric keypad in addition to an actual mouse. The 
structure stores the settings about the MouseKeys accessibility feature. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various settings and properties of MouseKeys: 
MKF_AVAILABLE = &H2 
The MouseKeys feature is available. 
MKF_CONFIRMHOTKEY = &H8 
Win 95/98 only: Open a confirmation dialog box when the user activates MouseKeys via 
the hot key. 
MKF_HOTKEYACTIVE = &H4 
Allow the user to toggle MouseKeys via the hot key: press Left Alt, Left Shift, and Num 
Lock simultaneously. 
MKF_HOTKEYSOUND = &H10 
Play a sound when the user toggles MouseKeys via the hot key. 
MKF_INDICATOR = &H20 
Win 95/98 only: Display an icon in the system tray while MouseKeys is on. 
MKF_MODIFIERS = &H40 
Win 95/98 only: Multiply the mouse speed by iCtrlSpeed while the Ctrl key is held. 
MKF_MOUSEKEYSON = &H1 
The MouseKeys feature is currently on. 
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MKF_REPLACENUMBERS = &H80 
Win 95/98 only: Only let the numeric keypad control the mouse cursor while Num Lock is 
on. If this flag is not set, only let the numeric keypad control the mouse cursor while Num 
Lock is off. 
iMaxSpeed 
The maximum speed of the mouse cursor. In Win NT, this must be between 10 and 360 inclusive. 
In Win 95/98, there is no limiting range. 
iTimeToMaxSpeed 
The length of time, in milliseconds, before the mouse cursor begins moving at the maximum 
speed. This must be between 1000 and 5000 inclusive. 
iCtrlSpeed 
Win 95/98: The multiplier to apply to the mouse speed when the Ctrl key is held. Win NT: 
Reserved -- set to 0. 
dwReserved1 
Reserved -- set to 0. 
dwReserved2 
Reserved -- set to 0. 


Used by: SystemParametersInfo 
Back to the index. 
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MSGBOXPARAMS Structure 


Type MSGBOXPARAMS 
cbSize As Long 
hwndOwner As Long 
hInstance As Long 
lpszText As String 
lpszCaption As String 
dwStyle As Long 
lpszicon As Long 
dwContextHelpiId As Long 
lpfnMsgBoxCallback As Long 
dwLanguagelId As Long 

End Type 


Description & Usage 


The MSGBOXPARAMSS structure stores the options used to create a message box. The information 
held by the structure specifies numerous settings used to determine the presentation and functionality of 
the message box. 


Visual Basic-Specific Issues 


To specifiy a pointer to the MsgBoxCallback callback function for the IpfnMsgBoxCallback data 


member, a dummy function must be used. Because the AddressOf operator is only valid inside a function 
call's argument list, a program-defined dummy function that simply returns the value passed to it is 
necessary to set the data member. For an example of such a dummy function, see the example for the 


MessageBoxIndirect function. 


Data Members 


cbSize 
The size in bytes of the structure. 
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hwndOwner 
A handle to the window which owns the message box. 
hInstance 
A handle to the instance of the application calling the function. 
IpszText 
The text to display in the body of the message box. 
IpszCaption 
The text to display in the title bar of the message box. 
dwStyle 
A combination of various flags specifying the behavior and appearance of the message box. The 
available flags are grouped according to function. If no flags in a certain group are specified, the 
default is used. 


Use one of the following flags to specify which buttons to display in the message box. (Note that 
MB_HELP can be combined with any of the other flags.) 
MB_ABORTRETRYIGNORE 
The message box contains the Abort, Retry, and Ignore buttons. 
MB_CANCELTRYCONTINUE 
Windows 2000: The message box contains the Cancel, Try Again, and Continue buttons. 
This is meant to replace the MB_ABORTRETRYIGNORE flag. 
MB_HELP 
Windows 95, 98, NT 4.0 or later, 2000: Add the Help button to the message box. When 
the user clicks the Help button, the WM_HELP message is sent to the owner of the 
message box (specified by the hWnd parameter). This flag can only be used by combining 
it with another button flag (1.e., the Help button cannot appear alone). 
MB_OK 
The message box contains the OK button. This is the default. 
MB_OKCANCEL 
The message box contains the OK and Cancel buttons. 
MB_RETRYCANCEL 
The message box contains the Retry and Cancel buttons. 
MB_YESNO 
The message box contains the Yes and No buttons. 
MB_YESNOCANCEL 
The message box contains the Yes, No, and Cancel buttons. 


Use one of the following flags to specify which icon to display in the message box: 
MB_ICONASTERISK, MB_ICONINFORMATION 

Display the information icon: a lowercase letter "1" inside a blue circle. 
MB_ICONERROR, MB_ICONHAND, MB_ICONSTOP 

Display the stop-sign icon in the message box. 
MB_ICONEXCLAMATION, MB_ICONWARNING 

Display the exclamation-point icon in the message box. 
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MB_ICONQUESTION 
Display the question-mark icon in the message box. 
MB_USERICON 
Use the icon specified by the /pszlcon data member instead of a predefined system icon. 


Use one of the following flags to specify which button is selected by default: 
MB_DEFBUTTON1 

The first button is the default. This is the default. 
MB_DEFBUTTON2 

The second button is the default. 
MB_DEFBUTTON3 

The third button is the default. 
MB_DEFBUTTON4 

The fourth button is the default. 


Use one of the following flags to specify the modality of the message box: 
MB_APPLMODAL 
The message box is application-modal. The user cannot switch to any other windows 
owned by the application until he or she first closes the message box. This is the default. 
MB_SYSTEMMODAL 
The message box is system-modal. The user cannot switch to any other windows until he 
or she first closes the message box. 
MB_TASKMODAL 
The message box is thread-modal. The user cannot switch to any other windows owned by 
the calling thread until he or she first closes the message box. 





Use zero or more of the following flags to specify other options for the message box: 
MB_DEFAULT_DESKTOP_ONLY 
Windows NT, 2000: Same as MB_SERVICE_NOTIFICATION, except that the system 
will display the message box only on the interactive window station's default desktop. 
MB_RIGHT 
The text in the message box is right-justified. 
MB_RTLREADING 
Display the message text and caption using right-to-left reading order if desired by the 
system language. 
MB_SETFOREGROUND 
Make the message box the foreground window. 
MB_TOPMOST 
Make the message box a topmost window. 
MB_SERVICE_NOTIFICATION 
Windows NT 4.0 or later, 2000: The calling thread is a service notifying the user of an 
event. The hWnd parameter must be 0. 
MB_SERVICE_NOTIFICATION_NT3X 
Windows NT 3.1 through 3.51: Same as MB_SERVICE_NOTIFICATION. The value of 
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this flag changed with the release of NT 4.0. 

IpszIcon 
The icon resource to use for the message box's icon. This can be specified either by an integer 
resource identifier or by a pointer to a string equal to the resource's name. Either way, the resource 
must be owned by the instance specified by hInstance. 

dwContextHelpId 
The help context ID which identifies the appropriate help topic to display if the user clicks the 
Help button. This information is passed to the callback function specified by 
lpfnMsgBoxCallback. 

lpfnMsgBoxCallback 
A pointer to the MsgBoxCallback callback function to process help events for the message box. 
This function is invoked whenever the user clicks the Help button. If this is 0 and the user clicks 
the Help button, a WM_HELP message is sent to the message box's owner. 

dwLanguageld 
The language ID, retrieved by the MAKELANGID macro, which identifies the language to use to 
display the message box's buttons. This language must already be installed on the computer. 


Constant Definitions 


Const MB _ABORTRETRYIGNORE = &H2 
Const MB_CANCELTRYCONTINUE = &H2 
Const MB_HELP = &H4000 

Const MB_OK = &H0O 

Const MB _OKCANCEL = &H1 

Const MB_RETRYCANCEL = &H5 

Const MB_YESNO = &H4 

Const MB_YESNOCANCEL = &H3 

Const MB_ICONASTERISK = &H40 
Const MB _ICONERROR = &H10 


Const MB_TCONEXCLAMATION = &H30 
Const MB_ICONHAND = &H10 
Const MB_TCONINFORMATION = &H40 


Const MB_ICONQUESTION = &H20 
Const MB_ICONSTOP = &H10 
Const MB_ICONWARNING = &H30 
Const MB_USERICON = &H80 
Const MB_DEFBUTTONI1 = &H0O 











Const MB_DEFBUTTON2 = &H100 
Const MB_DEFBUTTON3 = &H200 
Const MB_DEFBUTTON4 = &H300 





Const MB_APPLMODAL = &HO 
Const MB_SYSTEMMODAL = &H1000 
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Const MB_TASKMODAL = &H2000 

Const MB_DEFAULT_DESKTOP_ONLY = &H20000 
Const MB_RIGHT = &H80000 

Const MB_RTLREADING = &H100000 

Const MB_SETFOREGROUND = &H10000 

"Const MB TOPMOST = ??? 

"Const MB_SERVICE_NOTIFICATION = ??? 
"Const MB_SERVICE_NOTIFICATION_NT3X = ??? 


Used By 





MessageBoxIndirect 


Back to the Structure list. 
Back to the Reference section. 
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MULTIKEYHELP Structure 


Type MULTIKEYHELP 

mkSize As Long 

mkKeylist As Byte 

szKeyphrase As String * 255 ' can actually be any length 
End Type 


Description & Usage 


The MULTIKEYHELP structure stores one or more keywords to search for in a Windows Help file as 
well as the identifier of the alternate keyword table to search. Note that szKeyphrase can be of any length 
needed -- 255 bytes is just one possible value. 


Visual Basic-Specific Issues 


None. 


Data Members 


mkSize 
The size in bytes of the structure. 
mkKeylist 
The identifier of the alternate keyword table to search. 
szKeyphrase 
A null-terminated string holding one or more keywords to search for. If using more than one 
keyword, separate each keyword with a semicolon. 


Used By 


WinHelp 
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Go back to the alphabetical Structure listing. 
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NEWTEXTMETRIC Structure 


Type NEWTEXTMETRIC 
tmHeight As Long 
tmAscent As Long 
tmDescent As Long 
tmInternalLeading As Long 
tmExternalLeading As Long 
tmAveCharWidth As Long 
tmMaxCharWidth As Long 
tmWeight As Long 
tmOverhang As Long 
tmDigitizedAspectX As Long 
tmDigitizedAspectY As Long 
tmFirstChar As Byte 
tmLastChar As Byte 
tmDefaultChar As Byte 
tmBreakChar As Byte 
tmItalic As Byte 
tmUnderlined As Byte 
tmStruckOut As Byte 
tmPitchAndFamily As Byte 
tmCharSet As Byte 
ntmFlags As Long 
ntmSizeEM As Long 
ntmCellHeight As Long 
ntmAveWidth As Long 

End Type 





Description & Usage 


The NEWTEXTMETRIC structure holds the text metrics of a font. The structure describes many 
physical attributes of the font. Unless otherwise specified, all size measurements of the font stored in the 
structure are in the logical units of the device the font is being used on, so the same font may have a 
different "scale" if used on a different device. 
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Visual Basic-Specific Issues 


None. 


Data Members 


tmHeight 
The height of the font's characters (equal to the sum of tmAscent and tmDescent). 
tmAscent 
The ascent (units above the base line) of the font's characters. 
tmDescent 
The descent (units below the base line) of the font's characters. 
tmInternalLeading 
The amount of leading space inside the bounds of tmHeight where accent marks or other 
diacritical marks may appear. 
tmExternalLeading 
The amount of leading space placed between rows of text in which the font does not draw. 
tmAveCharWidth 
The average width of the font's characters, usually identified as the width of the "x" character. 
This value does not include extra space required for bold or italic characters. 
tmMaxCharWidth 
The width of the widest character of the font. This value does not include extra space required for 
bold or italics. 
tmWeight 
One of the following flags specifying the boldness (weight) of the font: 
FW_DONTCARE 
Default weight. 
FW_THIN 
Thin weight. 
FW_EXTRALIGHT 
Extra-light weight. 
FW_ULTRALIGHT 
Same as FW_EXTRALIGHT. 
FW_LIGHT 
Light weight. 
FW_NORMAL 
Normal weight. 
FW_REGULAR 
Same as FW_NORMAL. 
FW_MEDIUM 
Medium weight. 
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FW_SEMIBOLD 
Semi-bold weight. 
FW_DEMIBOLD 
Same As FW_SEMIBOLD. 
FW_BOLD 
Bold weight. 
FW_EXTRABOLD 
Extra-bold weight. 
FW_ULTRABOLD 
Same as FW_EXTRABOLD. 
FW_HEAVY 
Heavy weight. 
FW_BLACK 
Same as FW_HEAVY. 
tmOverhang 
The extra width per string added to the font when synthesizing attributes such as boldface and 
italics. For a boldface effect, this is the distance by which the overstrike is offset. For an italics 
effect, this is the amount that the top of the character is sheared past the bottom of the character. 
tmDigitizedAspectX 
The horizontal aspect of the device for which the font was designed. 
tmDigitizedAspectY 
The vertical aspect of the device for which the font was designed. 
tmFirstChar 
The value of the first character defined in the font. 
tmLastChar 
The value of the last character defined in the font. 
tmDefaultChar 
The value of the character to substitute for characters not present in the font. 
tmBreakChar 
The value of the character to be used for work breaks for text justification. 
tmltalic 
If zero, the font is not an italic font. If a non-zero value, the font is an italic font. 
tmUnderlined 
If zero, the font is not an underlined font. If a non-zero value, the font is an underlined font. 
tmStruckOut 
If zero, the font is not a strikeout font. If a non-zero value, the font is a strikeout font. 
tmPitchAndFamily 
A bitwise OR combination of exactly one *_PITCH flag specifying the pitch of the font and 
exactly one FF_* flag specifying the font face family of the font: 
DEFAULT_PITCH 
The default pitch. 
FIXED_PITCH 
Fixed pitch. 
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VARIABLE _ PITCH 

Variable pitch. 
FF_DECORATIVE 

Showy, decorative font face. 
FF_DONTCARE 

Do not care about the font face. 
FF_MODERN 

Modern font face (monospaced, sans serif font). 
FF_ROMAN 

Roman font face (proportional-width, serif font). 
FF_SCRIPT 

Script font face which imitates script handwriting. 
FF_SWISS 

Swiss font face (proportional-width, sans serif font). 

tmCharSet 

One of the following flags identifying the character set of the font: 
ANSI_CHARSET 

ANSI character set. 
ARABIC_CHARSET 

Windows NT, 2000: Arabic character set. 
BALTIC_CHARSET 

Windows 95, 98: Baltic character set. 
CHINESEBIGS_CHARSET 

Chinese Big 5 character set. 
DEFAULT_CHARSET 

Default character set. 
EASTEUROPE_CHARSET 

Windows 95, 98: Eastern European character set. 
GB2312_CHARSET 

GB2312 character set. 
GREEK_CHARSET 

Windows 95, 98: Greek character set. 
HANGEUL_CHARSET 

HANDEUL character set. 
HEBREW_CHARSET 

Windows NT, 2000: Hebrew character set. 
JOHAB_CHARSET 

Windows 95, 98: Johab character set. 
MAC_CHARSET 

Windows 95, 98: Mac character set. 
OEM_CHARSET 

Original equipment manufacturer (OEM) character set. 
RUSSIAN_CHARSET 
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Windows 95, 98: Russian character set. 
SHIFTJIS_CHARSET 
ShiftJis character set. 
SYMBOL_CHARSET 
Symbol character set. 
THAI_CHARSET 
Windows NT, 2000: Thai character set. 
TURKISH_CHARSET 
Windows 95, 98: Turkish character set. 
ntmFlags 
Zero or more of the following flags identifying various properites or attributes of the font: 
NTM_BOLD 
The font is a bold font. 
NTM_DSIG 
Windows 2000: The font has a digital signature, which allows the font to be traced and 
ensures that the font has not been corrupted. 
NTM_ITALIC 
The font is an italic font. 
NTM_MULTIPLEMASTER 
Windows 2000: The font is a Multiple Master font. 
NTM_NONNEGATIVE_AC 
Windows 2000: No glyph in the font at any size as a negative A or C space. 
NTM_PS_OPENTYPE 
Windows 2000: The font is a PostScript OpenType font. 
NTM_REGULAR 
The font is a regular font. 
NTM_TT_OPENTYPE 
Windows 2000: The font is a TrueType OpenType font. 
NTM_TYPEI1 
Windows 2000: The font is a Type 1 font. 
nitmSizeEM 
The size of the em square for the font, measured in notional units. 
ntmCellHeight 
The height of the font, measured in notional units. 
ntmAvg Width 
The average width of the characters in the font, measured in notional units. 


Constant Definitions 


Const FW_DONTCARE = 0 
Const FW_THIN = 100 
Const FW_EXTRALIGHT = 200 
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Const FW_ULTRALIGHT = 200 
Const FW_LIGHT = 300 
Const FW_NORMAL = 400 
Const FW_REGULAR = 400 
Const FW_MEDIUM = 500 
Const FW_SEMIBOLD = 600 
Const FW_DEMIBOLD = 600 
Const FW_BOLD = 700 

Const FW_EXTRABOLD = 800 
Const FW_ULTRABOLD = 800 
Const FW_HEAVY = 900 
Const FW_BLACK = 900 
Const DEFAULT_PITCH = 0 
Const FIXED_PITCH = 1 
Const VARIABLE PITCH = 2 
Const FF_DECORATIVE 80 
Const FF_DONTCARE = 0 
Const FF_ROMAN = 16 
Const FF_SCRIPT = 64 
Const’ FF_SWISS = 32 
Const ANSI_CHARSET = 0 
Const ARABIC_CHARSET 178 
Const BALTIC_CHARSET = 186 
Const CHINESEBIG5_CHARSET = 136 
Const DEFAULT_CHARSET = 1 

Const EASTEUROPE_CHARSET = 238 
Const GB2312_CHARSET = 134 
Const GREEK_CHARSET = 161 

Const HANGEUL_CHARSET = 129 
Const HEBREW_CHARSET = 177 
Const JOHAB_CHARSET = 130 

Const MAC_CHARSET MA, 

Const OEM_CHARSET = 255 

Const RUSSIAN_CHARSET = 204 
Const SHIFTJIS_CHARSET = 128 
Const SYMBOL_CHARSET = 
Const THAI_CHARSET = 22 
Const TURKISH_CHARSET = 162 

Const NTM_BOLD = &H20 

Const NTM_DSIG = &H100000 

Const NTM_ITALIC = &H1 

Const NTM_MULTIPLEMASTER = &H40000 


Const NTM_NONNEGATIVE_AC = &H10000 





2 
2 
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Const NTIM_PS_OPENTYPE = &H20000 
Const NTM_REGULAR = &H100 
Const NIM_TYPE1 = &H80000 


Used By 


EnumFontFamProc, NEWTEXTMETRICEX 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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NEWTEXTMETRICEX Structure 


Type NEWTEXTMETRICEX 
ntmTm As NEWTEXTMETRIC 
ntmFontSig As FONTSIGNATURE 
End Type 








Description & Usage 


The NEWTEXTMETRICEX structure holds information describing the physical attributes of a font. In 
addition to storing the metrics of the font, the structure also identifies the font signature. 


Visual Basic-Specific Issues 


None. 


Data Members 


ntmIm 

The text metrics of the font. 
ntmFontSig 

The font signature of the font. 


Used By 


EnumFontFamExProc 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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NONCLIENTMETRICS Structure 


Type NONCLIENTMETRICS 
cbSize As Long 
iBorderWidth As Long 
iScrollWidth As Long 
iScrollHeight As Long 
iCaptionWidth As Long 
iCaptionHeight As Long 
lfCaptionFont As LOGFONT 
iSMCaptionWidth As Long 
iSMCaptionHeight As Long 
lfSMCaptionFont As LOGFONT 
iMenuWidth As Long 
iMenuHeight As Long 
lfMenuFont As LOGFONT 
lfStatusFont As LOGFONT 
lfMessageFont As LOGFONT 

End Type 


NONCLIENTMETRICS-type variables store information about the metrics associated with the non- 
client areas of windows. A window's non-client area includes its title bar, menu bar, and border -- i.e., the 
things around its area. The metrics specify various properies shared by all non-client areas. Note that all 
widths and heights referred to in the structure are measured in pixels. 


cbSize 

The size in bytes of the structure. 
iBorderWidth 

The thickness of a window's sizing border. 
iScrollWidth 

The width of a standard vertical scroll bar. 
iScrollHeight 

The height of a standard horizontal scroll bar. 
iCaptionWidth 

The width of a caption button. 
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iCaptionHeight 

The height of a caption button. 
lfCaptionFont 

Information about the logical font used to display text in a window's caption (title bar). 
iSMCaptionWidth 

The width of a small caption button. 
iSMCaptionHeight 

The height of a small caption button. 
iSMCaptionFont 

Information about the logical font used to display text in a small caption. 
iMenuWidth 

The width of a menu bar button. 
iMenuHeight 

The height of a menu bar button. 
[fMenuFont 

Information about the logical font used to display text in a menu bar. 
LfStatusFont 

Information about the logical font used to display text in a status bar. 
IfMessageFont 

Information about the logical font used to display text in message boxes. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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NOTIFYICONSTRUCTURE 


Type NOTIFYICONDATA 
cbhSize As Long 
hWnd As Long 
uID As Long 
uFlags As Long 
uCallbackMessage As Long 
hIcon As Long 
szTip As String * 64 ' Windows 2000: make this String * 128 
' The following data members are only valid in Windows 2000! 
(uncomment the following lines to use them) 
"dwState As Long 
‘dwStateMask As Long 
'szinio As String * 256 
"uTimeoutOrVersion As Long 
'szInfoTitle As String * 64 
‘dwinfoFlags As Long 
End Type 


Description & Usage 


The NOTIFYICONDATA structure stores information used to communicate with an icon in the system 
tray. The structure holds data that both identifies and describes settings for the icon in question. Windows 
2000 expands significantly on this structure, adding multiple data members not available in previous 
versions of Windows. 


Visual Basic-Specific Issues 


Windows 2000: Officially, the uTimeoutOrVersion data member is actually two separate data members, 
uTimeout and uVersion, which occupy the same space within the structure. Because Visual Basic does 
not support unions like C++ does, it is necessary to assign a single name to this data member. 
Nevertheless, using this pseudonym involves no loss of functionality. 
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Data Members 


cbSize 
The size in bytes of the structure. 
hWnd 
A handle to the window that owns the tray icon. This window will process any events generated 
by the icon. 
ulD 
The application-definied identifier that uniquely identifies the tray icon. This value allows a single 
window to own multiple tray icons, allowing the window to tell the difference between them. 
uF lags 
A combination of the following flags specifying which of the subsequent members of the 
structure contain useful data. Any data members not identified by a flag will be ignored. 
NIF_ICON 
The hIcon data member. 
NIF_MESSAGE 
The uCallbackMessage data member. 
NIF_TIP 
The szTip data member. 
NIF_STATE 
Windows 2000: The dwState and dwStateMask data members. 
NIF_INFO 
Windows 2000: Use a balloon-style tooltip instead of the regular pop-up tooltip. The 
szInfo, szTimeOut, szInfoTitle, and dwInfoFlags data members are used. 
uCallbackMessage 
An application-defined message identifier. This message is sent to the owning window whenever 
an event occurs related to the tray icon. These events are primarily when the mouse moves or 
clicks over the icon or when it receives keyboard input. The wParam parameter will be the 
application-defined identifier of the tray icon that generated the message. The /Param parameter 
will be the "real" Windows message identifier for the event that occured. 
hIcon 
A handle to the icon to display in the tray. 
szTip 
The null-terminated string to use for the icon's standard tooltip text. This text appears when the 
mouse cursor hovers over the icon. 
dwState 
Windows 2000: A combination of the following flags specifying the icon's state. Each flag is an 
independent toggle. 
NIS_HIDDEN 
The icon is hidden. 
NIS_SHAREDICON 
The icon is shared. 
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dwStateMask 
Windows 2000: A combination of the above flags that specifies which of the dwState flags to 
retrieve or modify. 
szInfo 
Windows 2000: The null-terminated string to use for the icon's balloon-style tooltip. 
uTimeoutOrVersion 
Windows 2000: The timeout value, in milliseconds, for the display of the balloon-style tooltip. If 
outside of Windows's allowable range, the timeout value will be "pushed" into the range of valid 
timeout periods. 


Or, if Shell_Notifylcon had been called with the NIM_VERSION flag, this instead specifies 
whether to use Windows 95 or Windows 2000 behavior. By default, Windows 2000 will use 
different messages in some cases to communicate with the owning window. For backward 
compatibility, you should use the older behavior. This is one of the following flags: 
0 
Use the Windows 95-style behavior. 
NOTIFYICON_VERSION 
Use the Windows 2000-style behavior. 
szInfoTitle 
The null-terminated string to use as the title of the balloon tooltip. This will appear in boldface 
above the regular text. 
dwlInfoFlags 
If desired, one of the following flags specifying the icon to display to the left of the balloon tooltip 
text. Set this as 0 to not use an icon. 
NITF_WARNING 
A warning icon. 
NIIF_ ERROR 
An error icon. 
NIIF_INFO 
An information icon. 


Constant Definitions 


Const NIF_ICON = &H2 

Const NIF_MESSAGE = &H1 

Const NIF_TIP = &H4 

Const NIF_STATE = &H8 

Const NIF_INFO = &H10 

Const NIS_HIDDEN = &H1 

Const NIS_SHAREDICON = &H2 
Const NOTIFYICON_VERSION = &H1 
Const NIIF_WARNING = &H30 
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Const NIIF_ERROR = &H10 
Const NIIF_INFO = &H40 


Used By 


Shell_NotifyIcon 


Back to the Structure list. 
Back to the Reference section. 
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NUMBERFMT Structure 


Type NUMBERFMT 
NumDigits As Long 
LeadingZero As Long 
Grouping As Long 
lpDecimalSep As String 
lpThousandSep As String 
NegativeOrder As Long 

End Type 


Description & Usage 


The NUMBERFM'T structure stores information about how to format a regular number for display. This 
structure allows a program to specify how it wants a number to be displayed, overriding the format used 
by a locale. 


Visual Basic-Specific Issues 


None. 


Data Members 


NumDigits 
The number of digits to display after the decimal point. 

LeadingZero 
If zero, do not pad the space to the right of the decimal point with zeros if there are fewer 
fractional digits than specified by NumDigits. If nonzero, then do pad the space. For example, if 
NumDigits is 3 and the number to display is 1.23, setting this data member to zero displays the 
number as "1.23". Setting this data member to any other value displays "1.230". 

Grouping 
The number of digits to include in each group to the left of the decimal point. Typically, groups of 
three are used (e.g., 1,234,567). Values in the range of 0-9 are valid. 
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lpDecimalSep 
The character to use for the decimal point. 
lpThousandSep 
The character to use for the grouping separator. 
NegativeOrder 
One of the following values specifying how to represent a negative number. An example of each 
is shown in the list below for the number -1.1. 


0 
(1.1) 
1 
-1.1 
2 
- 1.1 (space after the - sign) 
3 
1.1- 
4 


1.1 - (space before the - sign) 


Used By 


GetNumberFormat 


Back to the Structure list. 
Back to the Reference section. 
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OPENFILENAME Structure 


Type OPENFILENAME 
1StructSize As Long 
hwndOwner As Long 
hIinstance As Long 
lpstrFilter As String 
lpstrCustomFilter As String 
nMaxCustomFilter As Long 
nFilterIndex As Long 
lpstrFile As String 
nMaxFile As Long 
lpstrFileTitle As String 
nMaxFileTitle As Long 
lpstrInitialDir As String 
lpstrTitle As String 
flags As Long 
nFileOffset As Integer 
nFileExtension As Integer 
lpstrDefExt As String 
lCustData As Long 
lpfnHook As Long 
lpTemplateName As String 

End Type 


Description & Usage 


The OPENFILENAME structure is used to pass data to and from the GetOpenFileName and 
GetSaveFileName API functions. It stores both settings used to create the dialog box and the results of 
the user's selection. 


Visual Basic-Specific Issues 
Windows NT, 2000: If you do not use a string in the structure, it is imperative that you not set it to an 
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we 


empty string (""). If you do not use a string, leave it alone entirely. Any strings you do use must be 
explicitly terminated by a null character (vbNullChar). Failure to do either of these will cause 
GetOpenFileName and GetSaveFileName to fail. See the examples for those two functions for a 
demonstration on how strings must be handled. Of course, following these guidelines still works under 
Windows 95 and 98, but it isn't necessary. Your best bet is to follow the NT/2000 requirements so your 
code works under all versions of Windows. 


Data Members 


[StructSize 
The size in bytes of the structure. 

hwndOwner 
A handle to the window opening the file dialog box. 

hInstance 
If using a dialog box template, this is a handle to the memory block of the dialog box template to 
use. If using the default dialog box, set to 0. 

IlpstrFilter 
The entries in the File Type drop box. The format of the string is "name of file type" & 
vbNullChar & "mask" & vbNullChar ... for as many types, where name of file type is the text that 
appears in the list and mask is the extension mask. The string must end with a double vbNullChar. 

lpstrCustomFilter 
Similar to [pstrFilter, but holds only one file type name/mask pair that specifies a user-defined 
file type. If unused, set to an empty string. 

nMaxCustFilter 
The size in bytes of the string contained in /pstrCustomFilter. 

nFilterIndex 
The number (#1, #2, etc.) of data type specified lpstrFilter should be the default one. 

IpstrFile 
Set it as a series of blank spaces. If you want to specify a default filename, set this string to that 
default filename and pad it with spaces. Receives the complete path and filename of the file(s) the 
user selects. If multiple files are selected, each filename is separated by vbNullChar, and the 
entire string will end with a double vbNullChar. 

nMaxFile 
The length in characters of /pstrFile. 

IlpstrFileTitle 
Very similar to /pstrFile, but only receives the filename of the selected file. If multiple files are 
selected, this is not set to any useful data. 

nMaxFileTitle 
The length in characters of /pstrFileTitle. 

IpstrInitialDir 
The default directory to look in. 

IpstTitle 
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flags 


The text that appears in the dialog box's title bar. 


Zero or more of the following flags specifying how to create the file dialog box. Some of these 
flags will be set by the function after the call to reflect the user's selections. 
OFN_ALLOWMULTISELECT 
Allow the user to select multiple files (Open File dialog box only). 
OFN_CREATEPROMPT 
Prompt if a non-existing file is chosen. 
OFN_ENABLEHOOK 
Use the function specified by /pfnHook to process the dialog box's messages. 
OFN_ENABLESIZING 
Windows 98, 2000: Allow the dialog box to be resized. This is selected by default unless a 
hook function or custom template is specified. 
OFN_ENABLETEMPLATE 
Use the dialog box template specifed by hlnstance and IpTemplateName. 
OFN_ENABLETEMPLATEHANDLE 
Use the preloaded dialog box template specified by h/nstance. 
OFN_EXPLORER 
Use Windows Explorer-like additions to the file dialog box. This is selected by default 
unless a hook function or custom template is specified. 
OFN_EXTENSIONDIFFERENT 
The function sets this flag if the user selects a file with an extension different than the one 
specified by /pstrDefExt. 
OFN_FILEMUSTEXIST 
Only allow the selection of existing files. 
OFN_HIDEREADONLY 
Hide the Open As Read Only check box (Open File dialog box only). 
OFN_LONGNAMES 
Have the file dialog use long file names. This is automatically specified unless the 
Explorer-type extensions are not used. 
OFN_NOCHANGEDIR 
Don't change Windows's current directory to match the one chosen in the dialog box. 
OFN_NODEREFERENCELINKS 
If a shortcut file (.Ink or .pif) is chosen, return the shortcut file itself instead of the file or 
directory it points to. 
OFN_NOLONGNAMES 
Have the file dialog use short (8.3) file names. This is ignored unless a file dialog without 
Explorer-type extensions are not used. 
OFN_NONETWORKBUTTON 
Hide and disable the Network button in the dialog box. 
OFN_NOREADONLYRETURN 
The function sets this flag if the selected file is not read-only (Open File dialog box only). 
OFN_NOTESTFILECREATE 
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Do not create a test file before the box closes. Normally, this check is done to verify that 
the disk exists, that there is sufficient disk space, etc. However, this check should not be 
used on a create-nonmodify network share. Specifying this flag prevents this test from 
being done. 
OFN_NOVALIDATE 
Don't check the filename for invalid characters. 
OFN_OVERWRITEPROMPT 
Prompt the user if the chosen file already exists (Save File dialog box only). 
OFN_PATHMUSTEXIST 
Only allow the selection of existing paths. 
OFN_READONLY 
Check the Open As Read Only box. This flag is set after the function call if the box is 
checked after the user clicks OK. 
OFN_SHAREAWARE 
Ignore any file sharing violations. 
OFN_SHOWHELP 
Show the Help button in the dialog box. The button sends the WM_HELP message to the 
hook function specified by the structure. If no hook function is used, the Help button will 
do nothing. 
nFileOffet 
Receives the zero-based index specifying where in /pstrFile the pathname ends and the filename 
begins. 
nFileExtension 
Receives the zero-based index specifying where in /pstrFile the file extension begins. 
lpstrDefExt 
The default extension of a file (only for the Save dialog box). If a file is chosen with the *.* mask, 
the file gets this extension. Don't include the period. 
ICustData 
Information to pass to the hook function specified by /pfnHook whenever it is called. 
lpfnHook 
A pointer to a hook function to use to processes the dialog box's messages. For file dialogs with 
Explorer-type extensions, this is a pointer to a ORFNHookProc hook function. For file dialogs 
without those extensions, this is a pointer to a ORFNHookProcOldStyle hook function. If not using 
a hook function, set to 0. 
lpTemplateName 
The name of the dialog box template specified by hlnstance, if needed. 


Constant Definitions 


Const OFN_ALLOWMULTISELECT = &H200 
Const OFN_CREATEPROMPT = &H2000 
Const OFN_ENABLEHOOK = &H20 
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Const OFN_ENABLESIZING = &H800000 
Const OFN_ENABLETEMPLATE = &H40 

Const OFN_ENABLETEMPLATEHANDLE = &H80 
Const OFN_EXPLORER = &H80000 

Const OFN_EXTENSIONDIFFERENT = &H400 
Const OFN_FILEMUSTEXIST = &H1000 
Const OFN_HIDEREADONLY = &H4 

Const OFN_LONGNAMES = &H200000 

Const OFN_NOCHANGEDIR = &H8 


Const OFN_NODEREFERENCELINKS = &H100000 


Const OFN_NOLONGNAMES = &H40000 


Const OFN_NONETWORKBUTTON = &H20000 


Const OFN_NOREADONLYRETURN = &H8000 


Const. OFN_NOTESTPILECREATE &H10000 


Const OFN_NOVALIDATE = &H100 
Const OFN_OVERWRITEPROMPT = &H2 
Const OFN_PATHMUSTEXIST = &H800 
Const OFN_READONLY = &H1 

Const OFN_SHAREAWARE = &H4000 


Const OFN_SHOWHELP = &H10 


Used By 

















GetOpenFileName, GetSaveFileName 


Go back to the Structure listing. 
Go back to the Reference section index. 


Last Modified: September 24, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/o/openfilename.html 


http://216.26.168.92/vbapi/ref/o/openfilename.html (5 of 5) [9/1/2002 5:59:36 PM] 


Windows API Guide: OSVERSIONINFO Structure 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








OSVERSIONINFO Structure 


Type OSVERSIONINFO 
dwOSVersionInfoSize As Long 
dwMajorVersion As Long 
dwMinorVersion As Long 
dwBuildNumber As Long 
dwPlatformiId As Long 
szCSDVersion As String * 128 

End Type 


OSVERSIONINFO-type variables hold information about the version of Windows currently running. 
This structure holds various pieces of information identifying the version number, platform, and more 
about Windows. 


dwOSVersionInfoSize 
The size of the structure. 
dwMajorVersion 
The major version number; 1.e., the part of the version number before the first period. 
dwMinorVersion 
The minor version number; i.e., the part of the version number after the first period. 
dwBuildNumber 
The build number of the version. 
dwPlatformID 
Exactly one of the following flags identifying which platform of Windows is running (for 
example, Windows 95, Windows NT, etc.): 
VER_PLATFORM_WIN32s = 0 
Windows 3.x is running, using the Win32s pseudo-32-bit enhancements. 
VER_PLATFORM_WIN32_WINDOWS = 1 
Windows 95 or 98 is running. 
VER_PLATFORM_WIN32_NT = 2 
Windows NT is running. 
szCSDVersion 
More information about the operating system. 


Used by: GetVersionEx 
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Go back to the alphabetical Structure listing. 
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OVERLAPPED Structure 


Type OVERLAPPED 
Internal As Long 
InternalHigh As Long 
Offset As Long 
OffsetHigh As Long 
hEvent As Long 

End Type 


Description & Usage 


The OVERLAPPED structure tells file access functions what part of a file to read or write when 
asynchronous (overlapped) file access is used. The structure mainly holds the location within the file to 
begin the read or write operation. 


Visual Basic-Specific Issues 


None. 


Data Members 


Internal 
Used by Windows -- do not set. 
InternalHigh 
Used by Windows -- do not set. 
Offset 
Low-order dword of the 64-bit position in the file to start reading or writing to. 
OffsetHigh 
High-order dword of the 64-bit position in the file to start reading or writing to. 
hEvent 
Receives a handle to an event identifying the signaled state once the transfer is complete. 
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Used By 


ReadFile, WriteFile 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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POINT TYPE Structure 


Type POINT TYPE 
x As Long 
y As Long 
End Type 


Description & Usage 


The POINT_TYPE structure holds the (x,y) coordinate of a point. This structure is used throughout the 
API for storing the coordinates of a point. 


Visual Basic-Specific Issues 


Officially, this structure is called POINT. However, that violates the case-sensitive name spacing of 
Visual Basic because Visual Basic contains an intrinsic function called Point. The Windows API Guide 
calls this structure POINT_TYPE to avoid the naming collision. (Microsoft instead likes to call this 
structure POINT_API in Visual Basic contexts.) 


Data Members 


The x coordinate of the point. 


The y coordinate of the point. 


Used By 


CreatePolygonRgn, CreatePolyPolygonRgn, GetBrushOrgEx, GetCursorPos, HELPINFO, LOGPEN, 


MAKEPOINTS, MoveToEx, PolyBezier, PolyBezierTo, Polygon, Polyline, PolyPolygon, PolylineTo, 
PolyPolyline, SetBrushOrgEx, WinHelp 


http://216.26.168.92/vbapi/ref/p/point_type.html (1 of 2) [9/1/2002 5:59:51 PM] 


Windows API Guide: POINT_TYPE Structure 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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PRINTDLG_TYPE Structure 


Type PRINTDLG_TYPE 
1StructSize As Long 
hwndOwner As Long 
hDevMode As Long 
hDevNames As Long 
hdc As Long 
flags As Long 
nFromPage As Integer 
nToPage As Integer 
nMinPage As Integer 
nMaxPage As Integer 
nCopies As Integer 
hIinstance As Long 
iCustData As Long 
lpfnPrintHook As Long 
lpfnSetupHook As Long 
lpPrintTemplateName As String 
lpSetupTemplateName As String 
hPrintTemplate As Long 
hSetupTemplate As Long 

End Type 


PRINTDLG_TYPE-type variables store the necessary information to use a Print common dialog box or 
a Print Setup common dialog box. This structure holds all information necessary to initialize the box and 
receives the data selected by the user. Set the various members for the box's default selections -- they will 
be set by the called function to the selections of the user. Note that two other structures, DEVMODE and 
DEVNAMES, are included by specifying handles to a memory block. These memory blocks contain a 
copy of each structure's data. See the example for PrintDlg for information on how to create, use, and 
free these memory blocks. 


[StructSize 
The size in bytes of this structure. 
hwndOwner 
A handle to the window opening the dialog box, if any. 
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hDevMode 


A handle to the memory block holding the information contained in a DEVMODE structure. This 
data specifies information about the printer. 


hDevNames 


hdc 


flags 


A handle to the memory block holding the information contained ina DEVNAMES structure. 
This data specifies the driver name, printer name, and port name(s) of the printer. 


Receives either a device context or an information context (depending on the value set as flags) to 
the printer the user selected. 


Zero or more of the following flags specifying various options for creating the Print or Print Setup 
dialog. Note that when PrintDlg returns, many of these flags will be set by the function to indicate 
selections by the user: 
PD_ALLPAGES = &H0 
Select the All Pages radio button. 
PD_COLLATE = &H10 
Check the Collate check box. If this flag is set when the function returns, the user checked 
the box and the printer doesn't automatically support collation. If the box is checked and 
the printer does support it, this flag will not be set. 
PD_DISABLEPRINTTOFILE = &H80000 
Disable the Print to File check box. 
PD_ENABLEPRINTHOOK = &H1000 
Use the hook function pointed to by [pfnPrintHook to process the Print dialog box's 
messages. 
PD_ENABLEPRINTTEMPLATE = &H4000 
Use the Print dialog box template specified by /pPrintTemplateName. 
PD_ENABLEPRINTTEMPLATEHANDLE = &H10000 
Use the preloaded Print dialog box template specified by hPrintTemplate. 
PD_ENABLESETUPHOOK = &H2000 
Use the hook function pointed to by lpfnSetupHook to process the Print Setup dialog box's 
messages. 
PD_ENABLESETUPTEMPLATE = &H8000 
Use the Print Setup dialog box template specified by /pSetupTemplateName. 
PD_ENABLESETUPTEMPLATEHANDLE = &H20000 
Use the preloaded Print Setup dialog box template specified by hSetupTemplate. 
PD_HIDEPRINTTOFILE = &H100000 
Hide the Print to File check box. 
PD_NONETWORKBUTTON = &H200000 
Do not display any buttons associated with the network. 
PD_NOPAGENUMS = &H8 
Disable the Page Range radio button and edit boxes. 
PD_NOSELECTION = &H4 
Disable the Selection radio button. 
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PD_NOWARNING = &H80 
Do not warn the user if there is no default printer. 
PD_PAGENUMS = &H2 
Select the Page Range radio button. 
PD_PRINTSETUP = &H40 
Display the Print Setup dialog box instead of the Print dialog box. 
PD_PRINTTOFILE = &H20 
Select the Print to File check box. 
PD_RETURNDC = &H100 
Return a device context to the selected printer as hdc. 
PD_RETURNDEFAULT = &H400 
Instead of displaying either dialog box, simply load information about the default printer 
into hDevMode and hDevNames. For this to work, those two values must be set to 0 before 
calling the function. 
PD_RETURNIC = &H200 
Return an information context to the selected printer as hdc. 
PD_SELECTION = &H1 
Select the Selection radio button. 
PD_SHOWHELP = &H800 
Display the Help button. 
PD_USEDEVMODECOPIES = &H40000 
Same as PD_USEDEVMODECOPIESANDCOLLATE. 
PD_USEDEVMODECOPIESANDCOLLATE = &H40000 
If the printer does not automatically support multiple copies or collation, disable the 
corresponding options in the dialog box. The number of copies to print and the collation 
setting will be placed into hDevMode. The information returned to this structure will 
specify the number of pages and the collation which the program must print with -- the 
printer will print the copies or collate itself. 
nFromPage 
The value entered in the From Page text box, specifying which page begin printing at. 
nToPage 
The value entered in the To Page text box, specifying which page to stop printing at. 
nMinPage 
The minimum allowable value for nFromPage and nToPage. 
nMaxPage 
The maximum allowable value for nFromPage and nToPage. 
nCopies 
The number of copies the program needs to print. 
hInstance 
A handle to the application instance which has the desired dialog box template. 
ICustData 
A program-defined value to pass to whichever hook function is used. 
lpfnPrintHook 
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A handle to the program-defined hook function to use to process the Print dialog box's messages. 
lpfnSetup Hook 
A handle to the program-defined hook function to use to process the Print Setup dialog box's 
messages. 
lpPrintTemplateName 
The name of the Print dialog box template to use from the application instance specified by 
hInstance. 
lpSetupTemplateName 
The name of the Print Setup dialog box template to use from the application instance specified by 
hInstance. 
hPrintTemplate 
A handle to the preloaded Print dialog box template to use. 
hSetupTemplate 
A handle to the preloaded Print Setup dialog box template to use. 


Used by: PrintDlg 


Go back to the alphabetical Structure listing. 
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PRINTER_DEFAULTS Structure 


Type PRINTER_DEFAULTS 
pDatatype As String 
pDevMode As DEVMODE 
DesiredAccess As Long 

End Type 


Description & Usage 


The PRINTER_DEFAULTS structure specifies some settings for opening a printer. The structure also 
contains information to use to initialize the printer. 


Visual Basic-Specific Issues 


None. 


Data Members 


pDatatype 
The name of the default data type for the printer. 
pDevMode 
Information used to provide the initialization settings for the printer. 
DesiredAccess 
Windows NT, 2000: One of the following flags specifying access rights to the printer: 
PRINTER_ACCESS_ADMINISTER 
Access to perform administrative tasks. 
PRINTER_ACCESS_USE 
Access to perform basic printing operations. 
PRINTER_ALL_ACCESS 
Access to perform all administrative and basic printing tasks except for synchronization. 
Windows 95, 98: Reserved -- set to 0. 
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Constant Definitions 


Const PRINTER_ACCESS_ADMINISTRATOR = &H4 
Const PRINTER_ACCESS_USE = &H8 
Const PRINTER_ALL_ACCESS = &HFOOOC 


Used By 


OpenPrinter 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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PRINTER_INFO_1 Structure 


Type PRINTER_INFO_1 
flags As Long 
pDescription As String 
pName As String 
pComment As String 

End Type 


PRINTER_INFO_1-type variable store information about a printer. This structure stores a few pieces of 
information relating to a printer. 


flags 
One or more of the following flags providing information about the printer: 
PRINTER_ENUM_CONTAINER = &H8000 
The object the structure describes is a container, such as a print server controlling multiple 
printers. 
PRINTER_ENUM_EXPAND = &H4000 
The program should further enumerate the printer if default expansion on it is enabled. 
PRINTER_ENUM_ICON1 = &H10000 
To represent the printer, the program should use an icon representing a top-level network 
name. 
PRINTER_ENUM_ICON2 = &H20000 
To represent the printer, the program should use an icon representing a network domain. 
PRINTER_ENUM_ICON3 = &H40000 
To represent the printer, the program should use an icon representing a print server. 
PRINTER_ENUM_ICON8 = &H800000 
To represent the printer, the program should use an icon representing a printer. 
pDescription 
A description of the printer. 
pName 
The name of the printer. 
pComment 
Comments or a brief description of the printer. 


Used by: EnumPrinters 
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PRINTER_INFO 2 Structure 


Type PRINTER_INFO_2 
pServerName As String 
pPrinterName As String 
pShareName As String 
pPortName As String 
pDriverName As String 
pComment As String 
pLocation As String 
pDevMode As DEVMODE 
pSsepFile As String 
pPrintProcessor As String 
pDatatype As String 
pParameters As String 
pSecurityDescriptor As SECURITY DESCRIPTOR 
Attributes As Long 
Priority As Long 
DefaultPriority As Long 
StartTime As Long 
UntilTime As Long 
status As Long 
cJobs As Long 
AveragePPM As Long 

End Type 





PRINTER_INFO_2-type variables hold a multitude of information about a printer. Its member values, 
along with substructures inside of it, identify most pieces of information about a printer which Windows 
can provide. 


pServerName 

The name of the network server which contols the printer, if any. 
pPrinterName 

The name of the printer. 
pShareName 

The name of the sharepoint of the printer on the network, if any. 
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pPortName 
A comma-separated list of the printer port(s) the printer is connected to, such as LPT1:. 
pDriverName 
The name of the printer driver. 
pComment 
A comment about or a brief description of the printer. 
pLocation 
The physical location of the printer (usually applies to network printers). 
pDevMode 
Various default settings and attributes of the printer. 
pSepFile 
The file that contains the separator page printed between jobs. 
pPrintProcessor 
The name of the print processor the printer uses. 
pDatatype 
The name of the data type used to record the print jobs. 
pParameters 
Default parameters for the print processor. 
pSecurityDescriptor 
Security information about the printer. 
Attributes 
One or more of the following flags specifying various attributes of the printer: 
PRINTER_ATTRIBUTE_DEFAULT = &H4 
The default printer. 
PRINTER_ATTRIBUTE_DIRECT = &H2 
There is a direct connection to the printer (?). 
PRINTER_ATTRIBUTE_DO_COMPLETE_FIRST = &H200 
Complete jobs on a first-come, first-serve basis (?). 
PRINTER_ATTRIBUTE_ENABLE_BIDI = &H800 
Win 95/98 only: BIDI is enabled (?). 
PRINTER_ATTRIBUTE_ENABLE_DEVQ = &H80 
DEVQ is enabled (?). 
PRINTER_ATTRIBUTE_KEEPPRINTEDJOBS = &H100 
The Printer keeps information on printed jobs (?). 
PRINTER_ATTRIBUTE_QUEUED = &H1 
The printer supports document queueing (?). 
PRINTER_ATTRIBUTE_SHARED = &H8 
The printer is shared on a network. 
PRINTER_ATTRIBUTE_WORK_OFFLINE = &H400 
Win 95/98 only: The printer can work offline (?). 
Priority 
The priority given to the printer by the print spooler. 
DefaultPriority 
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The default priority for a print job. 
StartTime 
The earliest time the printer will print a job, specified in minutes after midnight UTC (GMT or 
Zulu time). 
UntilTime 
The latest time the printer will print a job, specified in minutes after midnight UTC (GMT or Zulu 
time). 
Status 
One or more of the following flags specifying the printer's current status (Win NT only supports 
the PRINTER_STATUS_PAUSED and PRINTER_STATUS_PENDING_DELETION flags): 
PRINTER_STATUS_BUSY = &H200 
The printer is busy. 
PRINTER_STATUS_DOOR_OPEN = &H400000 
The door on the printer is open. 
PRINTER_STATUS_ERROR = &H2 
An error has occured. 
PRINTER_STATUS_INITIALIZING = &H8000 
The printer is initializing. 
PRINTER_STATUS_IO_ACTIVE = &H100 
I/O with the printer is active. 
PRINTER_STATUS_MANUAL_FEED = &H20 
The printer is loading paper using manual feed. 
PRINTER_STATUS_NO_TONER = &H40000 
The printer is out of toner. 
PRINTER_STATUS_NOT_AVAILABLE = &H1000 
The printer is not available. 
PRINTER_STATUS_OFFLINE = &H80 
The printer is offline. 
PRINTER_STATUS_OUT_OF_MEMORY = &H200000 
The printer is out of memory. 
PRINTER_STATUS_OUTPUT_BIN_FULL = &H800 
The printer's output bin is full. 
PRINTER_STATUS_PAGE_PUNT = &H80000 
The printer has aborted printing the current page because it is too complex to handle. 
PRINTER_STATUS_PAPER_JAM = &H8 
The printer's paper has jammed. 
PRINTER_STATUS_PAPER_OUT = &H10 
The printer is out of paper. 
PRINTER_STATUS_PAPER_PROBLEM = &H40 
There is a problem with the paper in the printer. 
PRINTER_STATUS_PAUSED = &H1 
The printer is paused. 
PRINTER_STATUS_PENDING_DELETION = &H4 
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A document in the print queue is pending deletion. 
PRINTER_STATUS_PRINTING = &H400 

The printer is printing. 
PRINTER_STATUS_PROCESSING = &H4000 

The printer is processing information. 
PRINTER_STATUS_TONER_LOW = &H20000 

The printer is low on toner. 
PRINTER_STATUS_USER_INTERVENTION = &H100000 

The user has intervened in printer operations. 
PRINTER_STATUS_WAITING = &H2000 

The printer is waiting. 
PRINTER_STATUS_WARMING_UP = &H10000 

The printer is warming up. 

AveragePPM 

The average number of pages the printer can print per minute. 


Used by: EnumPrinters 
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PRINTER_INFO 4 Structure 


Type PRINTIER_INFO_4 
pPrinterName As String 
pServerName As String 
Attributes As Long 

End Type 


PRINTER_INFO_4-type variables store a very terse set of information about a printer. The information 
is limited to the name of the printer and on which network server (if any) it is located on. 


pPrinterName 
The name of the printer. 
pServerName 
The name of the network server the printer is on, if it is a network printer. 
Attributes 
Exactly one of the following flags specifying whether the printer is locally connected or is on the 
network: 
PRINTER_ATTRIBUTE_LOCAL = &H40 
The printer is located on the network. 
PRINTER_ATTRIBUTE_NETWORK = &H10 
The printer is directly connected to the computer. 


Used by: EnumPrinters 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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PRINTER_INFO_5 Structure 


Type PRINTER_INFO_5 
pPrinterName As String 
pPortName As String 
Attributes As Long 
DeviceNotSelectedTimeout As Long 
TransmissionRetryTimeout As Long 
End Type 


PRINTER_INFO_5-type variables hold information about a printer. This structure only identifies a few 
of the possible pieces of information associated with a printer. 


pPrinterName 
The name of the printer. 
pPortName 
A comma-separated list of the ports the printer is connected to, such as LPT1:. 
Attributes 
Zero or more of the following flags identifying various attributes of the printer: 
PRINTER_ATTRIBUTE_DEFAULT = &H4 
The printer is the default printer. 
PRINTER_ATTRIBUTE_DIRECT = &H2 
The printer is physically connected to the computer (i.e., it is not a network printer). 
PRINTER_ATTRIBUTE_QUEUED = &H1 
The printer supports queueing (7). 
PRINTER_ATTRIBUTE_SHARED = &H8 
The printer is a network printer. 
PRINTER_ATTRIBUTE_WORK_OFFLINE = &H400 
The printer can work if the computer is not connected to the network (?). 
DeviceNotSelectedTimeout 
The maximum time, in milliseconds, between attempts to select the printer. 
TransmissionRetryTimeout 
The maximum time, in milliseconds, between document transmission retries. 


Used by: EnumPrinters 
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PROCESSENTRY32 Structure 


Type PROCESSENTRY32 
dwSize As Long 
cntUsage As Long 
th32ProcessID As Long 
th32DefaultHeapID As Long 
th32ModuleID As Long 
cntThreads As Long 
th32ParentProcessID As Long 
pcPriClassBase As Long 
dwFlags As Long 
szExeFile As String * 260 
End Type 


Description & Usage 


The PROCESSENTRY32 structure holds information about a process. This information is retrieved 
from a system snapshot via either Process32First or Process32Next. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwSize 

The length in bytes of the structure. 
cntUsage 

The number of references to the process. The process terminates once this drops to zero. 
th32ProcessID 

Identifier of the process. This value can be used by other API functions that work with processes. 
th32DefaultHeapID 
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Identifier of the default heap for the process. This value can only be used by the tool help API 
functions and no others. 

thModuleID 
Identifier of the process's module. This value can only be used by the tool help API functions and 
no others. 

cntThreads 
The number of threads started by the program. 

th32ParentProcessID 
The identifier of the process that created this process. This value can be used by other API 
functions that work with processes. 


pcPriClassBase 

The base priority by any threads created by this class. 
dwFlags 

Reserved -- do not use. 
szExeFile 


The filename of the executable file for the process. 


Used By 


Process32First, Process32Next 


Back to the Structure list. 
Back to the Reference section. 
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RECT Structure 


Type RECT 
left As Long 
top As Long 
right As Long 
bottom As Long 
End Type 


Description & Usage 


The RECT structure holds a rectangle. This structure defines a rectangle by storing the coordinates of its 
upper-left and lower-right corners. Generally, points lying along the bottom or right edges of the rectange 
are not considered to be inside the rectangle; however, points along the top or left edges are. 


Visual Basic-Specific Issues 


None. 


Data Members 


left 

The x-coordinate of the upper-left corner of the rectangle. 
top 

The y-coordinate of the upper-left corner of the rectangle. 
right 


The x-coordinate of the lower-right corner of the rectangle. 
bottom 
The y-coordinate of the lower-right corner of the rectangle. 


Used By 
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ClipCursor, CopyRect, CreateEllipticRgnIndirect, CreateRectRgnIndirect, EqualRect, FillRect, 
FrameRect, GetClipCursor, GetRgnBox, GetWindowRect, InflateRect, IntersectRect, InvertRect, 


IsRectEmpty, OffsetRect, PtInRect, RectInRegion, SetRect, SetRectEmpty, SubtractRect, 
SystemParametersInfo, TRMPARAMS, UnionRect 





Go back to the Structure listing. 
Go back to the Reference section index. 
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SECURITY ATTRIBUTES Structure 


Type SECURITY_ATTRIBUTES 
nLength As Long 
lpSecurityDescriptor As Long 
biInheritHandle As Boolean 

End Type 


Description & Usage 


The SECURITY_ATTRIBUTES structure defines the level and type of security protection to give an 
object. Note that security information is used much more frequently under Windows NT/2000 than it is 
under Windows 95/98. 


Visual Basic-Specific Issues 


None. 


Data Members 


nLength 
The size in bytes of the structure. 
IpSecurityDescriptor 
A pointer to a security descriptor for the object. To use the default security descriptor, set this to 
0. 
bInheritHandle 
Specifies whether the object's handle should be inherited by new processes or programs. 


Used By 


CreateDirectory, CreateDirectoryEx, CreateFile, RegCreateKeyEx 
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Go back to the alphabetical Structure listing. 
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SECURITY DESCRIPTOR 


Type SECURITY_DESCRIPTOR 
Revision As Byte 
Sbzl As Byte 
Control As Long 
Owner As Long 
Group As. Long 
Sacl As ACL 
Dacl As ACL 
End Type 


Description & Usage 


The SECURITY_DESCRIPTOR structure identifies security information about an object. This 
structure should NEVER be written to directly! Instead, use the set of API functions that read and write 
information to this structure. 


Visual Basic-Specific Information 


None. 


Data Members 


Revision 
Revision number of the information. 
Sbzl 
Reserved -- set to 0. This member simply aligns the other members in memory. 
Control 
Control identifier. 
Owner 
Owner identifier. 
Group 
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Group identifier. 
Sacl 
The system access-control list (ACL). 
Dacl 
The discretionary access-control list (ACL). 


Used By 


JOB_INFO_2, PRINTER_INFO_2 


Go back to the alphabetical Structure listing. 
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SERIALKEYS Structure 


Type SERIALKEYS 
cbhSize As Long 
dwFlags As Long 
lpszActivePort As String 
lpszPort AS String 
iBaudRate As Long 
iPortState As Long 

End Type 


SERIALKEYS-type variables store information about the SerialKeys accessibility feature. SerialKeys 
allows a device connected to a serial port to imitate the mouse and/or keyboard. This structure stores the 
settings for SerialKeys. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various settings and properties of SerialKeys: 
SERKF_ACTIVE = &H8 
SerialKeys is currently receiving input on the serial port. 
SERKF_AVAILABLE = &H2 
The SerialKeys feature is available. 
SERKF_INDICATOR = &H4 
Display an icon in the system tray while SerialKeys is on. 
SERKF_SERIALKEYSON = &H1 
SerialKeys is currently on. 
lpszActivePort 
The name of the serial port to read from. An empty string signifies no port. "Auto" means 
SerialKeys will monitor any otherwise unused serial ports. 
lpszPort 
Reserved. 
iBaudRate 
The baud rate of the port identified by /pszActivePort. Valid baud rates are 110, 300, 600, 1200, 
2400, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, and 256000. 
iPortState 
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Identifies the state of the port identified by /pszActivePort. O means that all input is ignored. 1 
means that the port is being monitored for SerialKeys input when not being used by other 
programs. 2 means that all input is sent to SerialKeys. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/serialkeys.html 


http://216.26.168.92/vbapi/ref/s/serialkeys.html (2 of 2) [9/1/2002 6:00:53 PM] 


Windows API Guide: SHELLEXECUTEINFO Structure 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








SHELLEXECUTEINFO Structure 


Type SHELLEXECUTEINFO 
cbhSize As Long 
fMask As Long 
hwnd As Long 
lpVerb As String 
lpFile As String 
lpParameters As String 
lpDirectory As String 
nShow As Long 
hinstApp As Long 
lpIDList As Long 
lpClass As String 
hkeyClass As Long 
dwHotKey As Long 
hIcon As Long 
hProcess As Long 

End Type 





Description & Usage 


The SHELLEXECUTEINFO structure holds the information passed to and from the ShellExecuteEx 
function. The structure stores the data telling the function what to do, and also receives data describing 
the function's result. 


Visual Basic-Specific Issues 


Data Members 


cbSize 
The size, in bytes, of the structure. 


[Mask 
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A combination of the following flags specifying which optional parts of the structure to use, and 
also specifying other options to use with the structure: 
SEE_MASK_CLASSKEY 
Use the hkeyClass member. 
SEE_MASK_CLASSNAME 
Use the [pClass member. 
SEE_MASK_CONNECTNETDRV 
Validate the file share and connect it to a drive letter. JpFile is the Universal Naming 
Convention (UNC) pathname of a file on the network. 
SEE_MASK_DOENVSUBST 
Expand any environment variables appearing inside [pDirectory or IpFile. 
SEE_MASK_FLAG_DDEWAIT 
If ShellExecuteEx starts a DDE conversation, wait for that conversation to finish before 
the function returns. 
SEE_MASK_FLAG_NO_UI 
Do not display an error dialog if an error occurs. 
SEE_MASK_HOTKEY 
Use the dwHotKey member. 
SEE_MASK_ICON 
Use the hIcon member. 
SEE_MASK_IDLIST 
Use the [pIDList member. 
SEE_MASK_INVOKEIDLIST 
Use the /pIDList member to invoke an application. 
SEE_MASK_NOCLOSEPROCESS 
Use the hProcess member. 
hwnd 
A handle to the window that is calling ShellExecuteEx, if any. 
lpVerb 
A string that specifies the action to perform on the file specified by /pFile. This may be one of the 
following strings, although others are possible: 
"explore" 
If [pFile is a path name, open it in a Windows Explorer window. 
"open" 
Open /pFile using its associated program. Opening an executable file runs it. This is the 
default action if none is specified. 
"print" 
Print /pFile using its associated program. 
lpFile 
The name of the file to open, print, execute, or whatever is specified by /pVerb. 
lpParameters 
Additional parameters to use to perform the action. This would typically be additional command- 
line options to use, especially when running an executable file. 
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lpDirectory 
The path name of the working directory to use. If this is not specified, the current directory is 
used. 
nShow 
One of the following flags specifying how to display any window opened as a result of the call to 
ShellExecuteEx: 
SW_HIDE 
Hide the window. 
SW_MAXIMIZE 
Maximize the window. 
SW_MINIMIZE 
Minimize the window. 
SW_RESTORE 
Restore the window (not maximized nor minimized). 
SW_SHOW 
Show the window. 
SW_SHOWMAXIMIZED 
Show the window maximized. 
SW_SHOWMINIMIZED 
Show the window minimized. 
SW_SHOWMINNOACTIVE 
Show the window minimized but do not activate it. 
SW_SHOWNA 
Show the window in its current state but do not activate it. 
SW_SHOWNOACTIVATE 
Show the window in its most recent size and position but do not activate it. 
SW_SHOWNORMAL 
Show the window and activate it (as usual). 
hInstApp 
If ShellExecuteEx is successful, this receives a handle to the instance of the application that was 
started. If the function failed, this receives one of the following flags identifying the error: 
SE_ERR_ACCESSDENIED 
Access was denied. 
SE_ERR_ASSOCINCOMPLETE 
File association information was incomplete. 
SE_ERR_DDEBUSY 
The DDE operation is busy. 
SE_ERR_DDEFAIL 
The DDE operation failed. 
SE_ERR_DDETIMEOUT 
The DDE operation timed out. 
SE_ERR_DLLNOTFOUND 
A required DLL was not found. 
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SE_ERR_FNF 
The file could not be found. 
SE_ERR_NOASSOC 
There is no associated program to use to perform the action. 
SE_ERR_OOM 
The computer is out of memory. 
SE_ERR_PNF 
The path could not be found. 
SE_ERR_SHARE 
A shared file cound not be opened. 
IpIDList 
A pointer to an ITEMIDLIST structure (PIDL) that identifies the file to execute. This member is 
only used if fMask contains SEE_MASK_IDLIST or SEE_MASK_INVOKEIDLIST. 
IpClass 
The name of the file class or globally unique identifier (GUID) to use. This member is only used 
if {Mask contains SEE_MASK_CLASSNAME. 
hkeyClass 
A handle to the registry key to use for the file class. This member is only used if fMask contains 
SEE_MASK_CLASSKEY. 
dwHotKey 
The hot key to associate with the application. The low-order word is the virtual-key code of the 
hot key, and the high-order word is a combination of the following flags specifying the modifier 
keys to use: 
HOTKEYF_ALT 
Use the Alt key as a modifier. 
HOTKEYF_CONTROL 
Use the Ctrl key as a modifier. 
HOTKEYF_EXT 
Use the extended key as a modifier. 
HOTKEYF_SHIFT 
Use the Shift key as a modifier. 
This member is only used if fMask contains SEE_ MASK_HOTKEY. 
hIcon 
A handle to the icon to use for the file class. This member is only used if fMask contains 
SEE_MASK_ICON. 
hProcess 
Receives a handle to the process that was started by the call to ShellExecuteEx. This member is 
only used if fMask contains SEE_MASK_NOCLOSEPROCESS. 


Constant Definitions 


Const SEE_MASK_CLASSKEY = &H3 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


SEE_MASK_CLASSNAME = &H1 
SEE_MASK_CONNECTNETDRV = &H80 
SEE_MASK_DOENVSUBST = &H200 
SEE_MASK_FLAG DDEWAIT = &H100 
SEE_MASK_FLAG NO_UI = &H400 
SEE_MASK_HOTKEY = &H20 
SEE_MASK_ICON = &H10 
SEE_MASK_IDLIST = &H4 
SEE_MASK_INVOKEIDLIST = GHC 
SEE_MASK_NOCLOSEPROCESS = &H40 





Const 
Const 
Const 
Const 
Const 
Const 
Const 


SW_HIDE = 0 
SW_MAXIMIZE = 3 
SW_MINIMIZE = 6 
SW_RESTORE = 9 
SW_SHOW = 5 
SW_SHOWMAXIMIZED = 


l 
N Ww 


SW_SHOWMINIMIZED = 
SW_SHOWMINNOACTIVE 
SW_SHOWNA = 8 
SW_SHOWNOACTIVATE = 4 
SW_SHOWNORMAL = 1 
SE_ERR_ACCESSDENIED = 5 
SE_ERR_ASSOCINCOMPLETE = 
SE_ERR_DDEBUSY = 30 
SE_ERR_DDEFAIL = 29 
SE_ERR_DDETIMEOUT = 
SE_ERR_DLLNOTFOUND = 
SE_ERR_FNF = 2 
SE_ERR_NOASSOC = 
SE_ERR_OOM = 8 
SE_ERR_PNF = 3 
SE_ERR_SHARE = 26 
HOTKEYF_ALT = &H4 
HOTREYF CONTROL, = 
HOTKEYF_EXT = &H8 
HOTKEYF_SHIFT = &H1 


Used By 


ShellExecuteEx 


II 
J 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 





27 


28 
32 





al 


&H2 


Back to the Structure list. 
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SHFILEINFO Structure 


Type SHFILEINFO 
hicon As Long 
iIcon As Long 
dwAttributes As Long 
szDisplayName As String * 260 
szTypeName As String * 80 

End Type 


Description & Usage 


The SHFILEINFO structure holds information about a file system object pertaining to the system shell. 
The structure can hold such information as a handle to its icon and its display name in the shell. 





Depending on the flags used in the SHGetFileInfo function, not all of the structure's data members may 
necessarily hold useful information. 


Visual Basic-Specific Issues 


None. 


Data Members 


hIcon 
A handle to the icon used to represent the file system object in the shell. Your program must 
destroy this icon via DestroyIcon after using it to save resources. 
icon 
The index of the file system's icon within the system image list. 
dwAttributes 
A combination of the following flags specifying the attributes of the file system object: 
FILE_ATTRIBUTE_ARCHIVE 
An archive file (which most files are). 
FILE_ATTRIBUTE_COMPRESSED 
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A file residing in a compressed drive or directory. 
FILE_ATTRIBUTE_DIRECTORY 
A directory instead of a file. 
FILE_ATTRIBUTE_HIDDEN 
A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL 
An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY 
A read-only file. 
FILE_ATTRIBUTE_SYSTEM 
A system file, used exclusively by the operating system. 
szDisplayName 
A null-terminated string specifying the name of the file system object as it appears in the system 
shell. For files, this will be the full path and filename. 
szTypeName 
A null-terminated string specifying the name of the type of the file system object. 


Constant Definitions 


Const FILE_ATTRIBUTE_ARCHIVE = &H20 
Const FILE_ATTRIBUTE_COMPRESSED = &H800 
Const FILE_ATTRIBUTE_DIRECTORY = &H10 
Const FILE_ATTRIBUTE_HIDDEN = &H2 

Const FILE_ATTRIBUTE_NORMAL = &H0O 

Const FILE_ATTRIBUTE_READONLY = &H1 
Const FILE_ATTRIBUTE_SYSTEM = &H4 


Used By 


SHGetFileInfo 











Go back to the alphabetical Structure listing. 


Go back to the Reference section index. 
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SHFILEOPSTRUCT Structure 


Type SHFILEOPSTRUCT 
hwnd As Long 
wFrunc As Long 
pFrom As String 
pro. As String 
fFlags As Integer 
fAnyOperationsAborted As Long 
hNameMappings As Long 
lpszProgressTitle As String 
End Type 


Description & Usage 


The SHFILEOPSTRUCT structure holds a description of a file operation to have the SHFileOperation 
function perform. The contents of the structure identify the operation itself (copy, move, delete, or 
rename) as well as the targeted files and any other options. In some cases, the structure also receives 
feedback information based on the actions of the operation. 


Visual Basic-Specific Issues 


Because of how Visual Basic byte-aligns structure contents, the SHFILEOPSTRUCT cannot be passed 
directly to SHFileOperation or any other API function. Instead, it must be copied to a byte array in such a 
way to correct for the improper byte alignment. Specifically, bytes 1 through 18 of the structure must 
immediately precede bytes 21 through 32. In other words, bytes 19 and 20 must be removed. (The given 
byte positions are given so that the first byte is byte #1.) The example code for SHFileOperation 
demonstrates the most straightforward way to correct for this problem. 


Data Members 


hwnd 
A handle to the window that is performing the file operation. 
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wFunc 


pFrom 


plo 


[Flags 


One of the following flags specifying which file operation to perform: 
FO_COPY 
Copy the files specified by pFrom to the location specified by pTo. 
FO_DELETE 
Delete the files specified by pFrom. (To send files to the Recycle Bin, use this file 
operation and include the FOF_ALLOWUNDO flag in fFlags.) 
FO_MOVE 
Move the files specified by pFrom to the location specified by pTo. 
FO_RENAME 
Rename the files specified by pFrom to the names specified by pTo. 


A list of one or more files that are the source of the file operation. If multiple files are specified, 
they must be separated by a null character. The entire string must be terminated by two null 
characters. Wildcard characters (* and ?) are allowed in the filenames. 


A list of one or more paths or files that are the target of the file operation. If multiple files or paths 
are specified, they must be separated by a null character. The entire string must be terminated by 
two null characters. Wildcard characters (* and ?) are sometimes allowed, depending on the 
operation. Always specify the entire path and filename for any files or directories. 


A combination of the following flags specifying other options or settings: 

FOF_ALLOWUNDO 
Allow the user to Undo the file operation, if possible. All paths must be fully qualified for 
this flag to work. 

FOF_FILESONLY 
If a *.* wildcard file is specified in pFrom or pTo, only perform the file operation on the 
files (and not the directories). 

FOF_MULTIDESTFILES 
pTo specifies multiple destination files -- one for each source file in pFrom -- instead of a 
single target for all source files. 

FOF_NOCONFIRMATION 
Do not prompt the user with any confirmation dialogs, instead assuming a "Yes to All" 
response. 

FOF_NOCONFIRMMKDIR 
Do not confirm the creation of a new directory if the file operation requires one to be 
made. 

FOF_NO_CONNECTED_ELEMENTS 
Windows 2000: Do not move connected files as a group; instead, move only the specified 
files. 

FOF_NOCOPYSECURITYATTRIBS 
Windows NT 4.71 and later, 2000: Do not copy the security attributes of the files. 

FOF_NOERRORUI 
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Do not display a message box if an error occurs. 
FOF_NORECURSION 
Only perform the file operation in the specified directory, not operating recursively into its 
subdirectories. 
FOF_RENAMEONCOLLISION 
If a file being moved, copied, or renamed conflicts with an existing file, give the file 
operated on a new name. 
FOF_SILENT 
Do not display a progress dialog box. 
FOF_SIMPLEPROGRESS 
Display a progress dialog box displaying the text specified by /pszProgressTitle but do not 
display the file names being processed. 
FOF_WANTMAPPINGHANDLE 
Create a SHNAMEMAPPING structure to identify any files that must be renamed as a 
result of the FOF_LRENAMEONCOLLISION flag. A handle to this structure is put into 
hNameMappings. 
FOF_WANTNUKEWARNING 
Windows 2000: Warn the user if a file is being deleted rather than being sent to the 
Recycle Bin. 
fAnyOperationsAborted 
Receives a nonzero value if the user aborted any file operations before they were complete. This 
receives 0 if all operations completed without user intervention. 
hNameMappings 
If fFlags contains FOF_WANTMAPPINGHANDLE, this receives a handle to an array of 
SHNAMEMAPPING structures that identify which files were renamed. After use, this handle 
must be freed by the SHFreeNameMappings function. NOTE: I have not been able to figure out 
how to use the mapping handle placed in this data member. If anyone knows how, please e-mail 
me. 
lpszProgressTitle 
If fFlags contains the FOF_SIMPLEPROGRESS flag, this is the text to display in the progress 
dialog box. This string must be null-terminated. 


Constant Definitions 


Const FO_COPY = &H2 

Const FO_DELETE = &H3 

Const FO_MOVE = &H1 

Const FO_RENAME = &H4 

Const FOF_ALLOWUNDO = &H40 
Const FOF_FILESONLY = &H80 
Const FOF _MULTIDESTFILES & H1 
Const FOF_NOCONFIRMATION = &H10 


http://216.26.168.92/vbapi/ref/s/shfileopstruct.html (3 of 4) [9/1/2002 6:01:06 PM] 


Windows API Guide: SHFILEOPSTRUCT Structure 


Const FOF_NOCONFIRMMKDIR = &H200 

Const FOF_NO_CONNECTED_ELEMENTS = &H1000 
Const FOF_NOCOPYSECURITYATTRIBS = &H800 
Const FOF_NOERRORUI = &H400 

Const FOF_RENAMEONCOLLISION = &H8 

Const FOF_SILENT = &H4 

Const FOF_SIMPLEPROGRESS = &H100 

Const FOF_WANTMAPPINGHANDLE = &H20 

Const FOF_WANTNUKEWARNING = &H2000 


Used By 











SHFileOperation 
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SHITEMID Structure 


Type SHITEMID 
cbSize As Integer 
abID As String * 256 ' can actually be any size, not necessarily 256 
End Type 


Description & Usage 


The SHITEMID structure holds the data of an item identifier. Since the ITEMIDLIST structure (to which 


this structure belongs) is almost never used explitly by a program, this structure also is usually not used 
directly. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 
The size in bytes of the structure. 

abID 
The data of the item identifier. The length of this parameter can vary. The format of its contents is 
undocumented and cannot be accessed directly. 


Used By 


ITEMIDLIST 





Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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SHNAMEMAPPING Structure 


Type SHNAMEMAPPING 
pszOldPath As String 
pszNewPath As String 
cchOldPath As Long 
cchNewPath As Long 

End Type 





Description & Usage 


The SHNAMEMAPPING structure identifies which files were renamed automatically as a result of a 
file operation. Files will automatically be renamed if a naming collision occurs during a copy, move, or 
rename operation performed by the SHFileOperation function. 


Visual Basic-Specific Issues 


None. 


Data Members 


pszOldPath 
The old path of the file. 
pszNewPath 
The new path of the file. 
cchOldPath 
The number of characters in pszOldPath. 
cchNewPath 
The number of characters in pszNewPath. 


Used By 
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SHFILEOPSTRUCT, SHFreeNameMappings 


Back to the Structure list. 
Back to the Reference section. 


Last Modified: April 16, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/s/shnamemapping.html 


http://216.26.168.92/vbapi/ref/s/shnamemapping.html (2 of 2) [9/1/2002 6:01:13 PM] 


Windows API Guide: SHQUERYRBINFO Structure 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








SHQUERYRBINFO Structure 


Type SHQUERYRBINFO 
cbhSize As Long 
164Size As ULARGE INTEGER 
i164NumItems As ULARGE INTEGER 
End Type 








Description & Usage 


The SHQUERYRBINFO holds information about a Recycle Bin. This Recycle Bin could be specific to 
a particular drive, or it could be the systemwide Recycle Bin. The structure holds the number of items in 
the Recycle Bin as well as the total size of all items in it. Both values are stored as unsigned 64-bit 
integers. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 

The size in bytes of the structure. 
164 Size 

The total size, in bytes, of all the items currently in the Recycle Bin. 
i64NumlItems 

The total number of items currently in the Recycle Bin. 


Used By 


SHQueryRecycleBin 
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SOCKADDR Structure 


Type SOCKADDR 
Ssin_family As Integer 
Sin_port As Integer 
Sin_addr As Long 
Sin_zero As String * 8 
End Type 


Description & Usage 


The SOCKADDR structure stores information about a connection to make to a network host. For 
TCP/IP connections, this is essentially the IP address of the remote host and the port to connect to. Other 
base protocols may have different requirements for the data to load into the structure, although no matter 
what, the structure will always be 16 bytes long. 


Visual Basic-Specific Issues 


None. 


Data Members 


sin_family 
The address family of the protocol to use. This will match the protocol used by the socket making 
the connection. 
sin_port 
The port number to connect to, in network byte order. 
sin_addr 
The IP address of the network host to connect to, in network byte order. 
sin_zero 
Padding data. If not using it, set all bytes to zero. 
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Used By 


connect 


Back to the Structure list. 
Back to the Reference section. 
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SOUNDSENTRY Structure 


Type SOUNDSENTRY 
cbhSize As Long 
dwFlags As Long 
iFSTextEffect As Long 
iFSTextEffectMSec As Long 
iFSTextEffectColorBits As Long 
iFSGrafEffect As Long 
iFSGrafEffectMSec As Long 
iFSGrafEffectColor As Long 
iWindowsEffect As Long 
iWindowsEffectMSec As Long 
lpszWindowsEffectDLL As String 
iWindowsEffectOrdinal As Long 
End Type 


Description & Usage 


The SOUNDSENTRY structure stores information about the SoundSentry accessibility feature. 
SoundSentry displays a visual cue whenever a sound is made. Windows NT, 2000: SoundSentry works 
for sounds played through both the internal speaker and multimedia devices. Windows 95, 98: 
SoundSentry only works for sounds played through the internal speaker. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 
The size in bytes of the structure. 
dwFlags 
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Zero or more of the following flags specifying various settings and properties of SoundSentry: 
SSF_AVAILABLE 
The SoundSentry accessibility feature is available. 
SSF_INDICATOR 
Display an icon in the system tray while SoundSentry is on. 
SSF_SOUNDSENTRYON 
SoundSentry is currently on. 
iF STextEffect 
Windows 95,98: Exactly one of the following flags specifying the visual cue to use while the user 
is in a full-screen text window (such as a full-screen MS-DOS window). Windows NT, 2000: 
Reserved -- set to 0. 
SSTF_BORDER 
Flash the screen border (the overscan area). 
SSTF_CHARS 
Flash the characters in the corners of the screen. 
SSTF_DISPLAY 
Flash the entire display. 
SSTF_NONE 
Do not display a visual cue. 
iF STextEffectMSec 
Windows 95, 98: The length of time in milliseconds to display the visual cue while in full-screen 
text mode. Windows NT, 2000: Reserved -- set to 0. 
iF STextEffectColorBits 
Windows 95, 98: The RGB value of the color to use for the visual cue while in full-screen text 
mode. Windows NT, 2000: Reserved -- set to 0. 
iF SGrafEffect 
Windows 95, 98: Exactly one of the following flags specifying the visual cue to display while the 
user is in a full-screen graphics window. Windows NT, 2000: Reserved -- set to 0. 
SSGF_DISPLAY 
Flash the entire display. 
SSGF_NONE 
Do not display a visual cue. 
iF SGrafEffectMSec 
Windows 95, 98: The length of time in milliseconds to display the visual cue while in full-screen 
graphics mode. Windows NT, 2000: Reserved -- set to 0. 
iF SGrafEffectColor 
Windows 95, 98: The RGB value of the color to use for the visual cue while in full-screen 
graphics mode. Windows NT: Reserved -- set to 0. 
iWindowsEffect 
Exactly one of the following flags specifying the visual cue to use while not in full-screen mode: 
SSWF_CUSTOM 
Windows 95, 98: Call the SoundSentryProc callback function exported by the dll file 
specified by IpszWindowsEffectDLL. 
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SSWF_DISPLAY 
Flash the entire display. 
SSWF_NONE 
Do not display a visual cue. 
SSWF_TITLE 
Flash the title bar of the active window. 
SSWF_WINDOW 
Flash the entire active window. 
iWindowsEffectMSec 
Windows 95, 98: The length of time in milliseconds to display the visual cue while not in full- 
screen mode. Windows NT, 2000: Reserved -- set to 0. 
lpszWindowsEffectDLL 
Windows 95, 98: The filename of the .dll file exporting the SoundSentryProc callback function 
to use, if applicable. Windows NT, 2000: Reserved. 
iWindowsEffectOrdinal 
Reserved -- set to 0. 


Constant Definitions 


Const SSF_AVAILABLE = &H2 
Const SSF_INDICATOR = &H4 
Const SSF_SOUNDSENTRYON = &H1 
Const SSTF_BORDER = 2 

Const SSTF_CHARS = 1 

Const SSTF_DISPLAY = 3 

Const SSTF_NONE = 0 

Const SSGF_DISPLAY = 3 

Const SSGF_NONE = 0 
Const SSWF_CUSTOM = 4 
Const SSWF_DISPLAY = 3 
Const SSWF_NONE = 0 
Const SSWF_TITLE = 1 
Const SSWF_WINDOW = 2 


Used By 





SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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STICKYKEYS Structure 


Type STICKYKEYS 
cbhSize As Long 
dwFlags As Long 

End Type 


STICKYKEYS-type variables store information about the StickyKeys accessibility feature. StickyKeys 
allows the user to simply press modifier keys (Ctrl, Alt, Shift) before pressing another key instead of 
having to press them simultaneously. For example, to give a Ctrl-S command, the user would simple 
press and release Ctrl, then press S (instead of pressing S while holding Ctrl). This structure holds the 
settings of StickyKeys. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various settings and properties of StickyKeys: 
SKF_AUDIBLEFEEDBACK = &H40 
Play a sound whenever the user latches, locks, or releases a modifer key. 
SKF_AVAILABLE = &H2 
The StickyKeys feature is available. 
SKF_CONFIRMHOTKEY = &H8 
Win 95/98 only: Open a confirmation dialog box when the user activates StickyKeys via 
the hot key. 
SKF_HOTKEYACTIVE = &H4 
Enable the user to toggle StickyKeys via the hot key: pressing Shift five times. 
SKF_HOTKEYSOUND = &H10 
Play a sound when the user toggles StickyKeys via the hot key. 
SKF_INDICATOR = &H20 
Win 95/98: Display an icon in the system tray while StickyKeys is on. 
SKF_STICKYKEYSON = &:H1 
StickyKeys is currently on. 
SKF_TRISTATE = &H80 
Allow the user to press a modifer key two times in a row to lock it; it will be unlocked 
after a third press. 
SKF_TWOKEYSOFF = &H100 
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Holding a modifier key and a normal key together deactivates StickyKeys. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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SYSTEMTIME Structure 


Type SYSTEMTIME 
wiear As Integer 
wMonth As Integer 
wDayOfWeek As Integer 
wDay As Integer 
wHour As Integer 
wMinute As Integer 
wSecond As Integer 
wMilliseconds As Integer 
End Type 


Description & Usage 


The SYSTEMTIME structure holds a date and time in an easily usable format. The structure is able to 
hold times precise to the millisecond, even though that information may not always be used. 


Sometimes, the SYSTEMTIME structure is used not to hold a "regular" date and time but to hold a 
shifting one (such as the 13t Sunday in January or the 314 Thursday of June). When this is used (usually 


when holding information relating to a time zone), wYear is always 0. wDay specifies which day, ranging 
from 1 (1st day) to 5 (5® or last day). wDayOfWeek identifies the precise day of the week. 


Visual Basic-Specific Issues 


None. 


Data Members 


wYear 
The four-digit year. 
wMonth 
The number identifying the month (1 = January, 2 = February, etc.). 
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wDayOfWeek 

The number identifying the day of the week (0 = Sunday, 1 = Monday, etc.). 
wDay 

The number of the day of the month. 
wHour 

The hour, in twenty-four hour format. 
wMinute 

The minutes. 
wSecond 

The seconds. 
wMilliseconds 

The milliseconds. 


Used By: 


FileTimeToSystemTime, GetDateFormat, GetLocalTime, GetSystemTime, GetTimeFormat, 
JOB_INFO_1, JOB_INFO_ 2, SetSystemTime, SystemTimeToFileTime, 
TIME ZONE INFORMATION 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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TEXTMETRIC Structure 


Type TEXTMETRIC 
tmHeight As Long 
tmAscent As Long 
tmDescent As Long 
tmInternalLeading As Long 
tmExternalLeading As Long 
tmAveCharWidth As Long 
tmMaxCharWidth As Long 
tmWeight As Long 
tmOverhang As Long 
tmDigitizedAspectX As Long 
tmDigitizedAspectY As Long 
tmFirstChar As Byte 
tmLastChar As Byte 
tmDefaultChar As Byte 
tmBreakChar As Byte 
tmItalic As Byte 
tmUnderlined As Byte 
tmStruckOut As Byte 
tmPitchAndFamily As Byte 
tmCharSet As Byte 

End Type 





Description & Usage 


The TEXTMETRIC structure holds the text metrics of a font. The structure describes many physical 
attributes of the font. Unless otherwise specified, all size measurements of the font stored in the structure 
are in the logical units of the device the font is being used on, so the same font may have a different 





"scale" if used on a different device. 


Visual Basic-Specific Issues 
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None. 


Data Members 


tmHeight 
The height of the font's characters (equal to the sum of tmAscent and tmDescent). 
tmAscent 
The ascent (units above the base line) of the font's characters. 
tmDescent 
The descent (units below the base line) of the font's characters. 
tmInternalLeading 
The amount of leading space inside the bounds of tmHeight where accent marks or other 
diacritical marks may appear. 
tmExternalLeading 
The amount of leading space placed between rows of text in which the font does not draw. 
tmAveCharWidth 
The average width of the font's characters, usually identified as the width of the "x" character. 
This value does not include extra space required for bold or italic characters. 
tmMaxCharWidth 
The width of the widest character of the font. This value does not include extra space required for 
bold or italics. 
tmWeight 
One of the following flags specifying the boldness (weight) of the font: 
FW_DONTCARE 
Default weight. 
FW_THIN 
Thin weight. 
FW_EXTRALIGHT 
Extra-light weight. 
FW_ULTRALIGHT 
Same as FW_EXTRALIGHT. 
FW_LIGHT 
Light weight. 
FW_NORMAL 
Normal weight. 
FW_REGULAR 
Same as FW_NORMAL. 
FW_MEDIUM 
Medium weight. 
FW_SEMIBOLD 
Semi-bold weight. 
FW_DEMIBOLD 
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Same As FW_SEMIBOLD. 
FW_BOLD 
Bold weight. 
FW_EXTRABOLD 
Extra-bold weight. 
FW_ULTRABOLD 
Same as FW_EXTRABOLD. 
FW_HEAVY 
Heavy weight. 
FW_BLACK 
Same as FW_HEAVY. 
tmOverhang 
The extra width per string added to the font when synthesizing attributes such as boldface and 
italics. For a boldface effect, this is the distance by which the overstrike is offset. For an italics 
effect, this is the amount that the top of the character is sheared past the bottom of the character. 
tmDigitizedAspectX 
The horizontal aspect of the device for which the font was designed. 
tmDigitizedAspectY 
The vertical aspect of the device for which the font was designed. 
tmFirstChar 
The value of the first character defined in the font. 
tmLastChar 
The value of the last character defined in the font. 
tmDefaultChar 
The value of the character to substitute for characters not present in the font. 
tmBreakChar 
The value of the character to be used for work breaks for text justification. 
tmltalic 
If zero, the font is not an italic font. If a non-zero value, the font is an italic font. 
tmUnderlined 
If zero, the font is not an underlined font. If a non-zero value, the font is an underlined font. 
tmStruckOut 
If zero, the font is not a strikeout font. If a non-zero value, the font is a strikeout font. 
tmPitchAndFamily 
A bitwise OR combination of exactly one *_PITCH flag specifying the pitch of the font and 
exactly one FF_* flag specifying the font face family of the font: 
DEFAULT_PITCH 
The default pitch. 
FIXED_PITCH 
Fixed pitch. 
VARIABLE_PITCH 
Variable pitch. 
FF_DECORATIVE 
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Showy, decorative font face. 
FF_DONTCARE 

Do not care about the font face. 
FF_MODERN 

Modern font face (monospaced, sans serif font). 
FF_ROMAN 

Roman font face (proportional-width, serif font). 
FF_SCRIPT 

Script font face which imitates script handwriting. 
FF_SWISS 

Swiss font face (proportional-width, sans serif font). 

tmCharSet 

One of the following flags identifying the character set of the font: 
ANSI_CHARSET 

ANSI character set. 
ARABIC_CHARSET 

Windows NT, 2000: Arabic character set. 
BALTIC_CHARSET 

Windows 95, 98: Baltic character set. 
CHINESEBIGS_CHARSET 

Chinese Big 5 character set. 
DEFAULT_CHARSET 

Default character set. 
EASTEUROPE_CHARSET 

Windows 95, 98: Eastern European character set. 
GB2312_CHARSET 

GB2312 character set. 
GREEK_CHARSET 

Windows 95, 98: Greek character set. 
HANGEUL_CHARSET 

HANDEUL character set. 
HEBREW_CHARSET 

Windows NT, 2000: Hebrew character set. 
JOHAB_CHARSET 

Windows 95, 98: Johab character set. 
MAC_CHARSET 

Windows 95, 98: Mac character set. 
OEM_CHARSET 

Original equipment manufacturer (OEM) character set. 
RUSSIAN_CHARSET 

Windows 95, 98: Russian character set. 
SHIFTJIS_CHARSET 

ShiftJis character set. 
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SYMBOL_CHARSET 

Symbol character set. 
THAI_CHARSET 

Windows NT, 2000: Thai character set. 
TURKISH_CHARSET 

Windows 95, 98: Turkish character set. 


Constant Definitions 


Const = 
Const 


Const 


F'W_DONTCARE 
FW_THIN 100 
FW_EXTRALIGHT 


200 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
CONSE 
Const 
Const 
Conse 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Conse 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
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FW_ULTRALIGHT 
FW_LIGHT 30 
F'W_NORMAL 4 
FW_REGULAR = 
FW_MEDIUM 





5 
FW_SEMIBOLD = 
FW_DEMIBOLD = 
FW_BOLD 700 
FW_EXTRABOLD 

FW_ULTRABOLD 

FW_HEAVY 90 
FW_BLACK 90 
DEFAULT_PITCH 
FIXED_PITCH 


VARIABLE_PITCH 


FF_DECORATIVE 
FF_DONTCARE 
FF_ROMAN 
BP SCRIPT 6 
FF_SWISS 32 
ANSI_CHARSET 


16 


ARABIC_CHARSET 
BALTIC. CHARSET 


200 
0 
00 
400 
00 
600 
600 


800 
800 
O 
0 


1 


8 


0 


2 

0 
O 

4 


O 


178 
186 


CHINESEBIG5_CHARSET 


DEFAULT_CHARSET 
EASTEUROPE_CHARSET 
GB2312_CHARSET 


GREEK_CHARSET 


HANGEUL_CHARSET 
HEBREW_CHARSET 


1 


134 
161 

12 
177 


9 


136 


238 
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Const JOHAB CHARSET = 130 
Const MAC_CHARSET = 77 

Const OEM CHARSET = 255 
Const RUSSIAN _CHARSET = 204 
Const SHIFTJIS_CHARSET = 128 
Const SYMBOL CHARSET = 
Const THAI _CHARSET = 22 
Const TURKISH_CHARSET = 162 


Used By 


EnumFontFamExProc, EnumFontFamProc 


2 
2 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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TIME ZONE INFORMATION Structure 


Type TIME_ZONE_INFORMATION 
Bias As Long 
StandardName (0 To 31) As Integer 
StandardDate As SYSTEMTIME 
StandardBias As Long 
DaylightName (0 To 31) As Integer 
DaylightDate As SYSTEMTIME 
DaylightBias As Long 

End Type 











TIME_ZONE_INFORMATION-type variables hold information about the system's selected time 
zone. The two arrays in the structure are actually strings, each element holding the ASCII codes for each 
character (the end of the string is marked by a NULL character, ASCII code 0). For more information 
about how to convert the arrays into usable data, see the example for GetTimeZoneInformation. 


Bias 
The difference in minutes between UTC (a.k.a. GMT) time and local time. It satisfies the formula 
UTC time = local time + Bias. 
StandardName(0 To 31) 
Holds the name of the time zone for standard time. 
StandardDate 
The relative date for when daylight savings time ends. 
StandardBias 
A number to add to Bias to form the true bias during standard time. 
DaylightTime(0 To 31) 
Holds the name of the time zone for daylight savings time. 
DaylightDate 
The relative date for when daylight savings time begins. 
DaylightBias 
A number to add to Bias to form the true bias during daylight savings time. 


Used by: GetTimeZoneInformaton 
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Go back to the alphabetical Structure listing. 
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TOGGLEKEYS Structure 


Type TOGGLEKEYS 
cbhSize As Long 
dwFlags As Long 

End Type 


TOGGLEKEYS-type variables store information about the ToggleKeys accessibility feature. 
ToggleKeys plays a sound whenever the user toggles Caps Lock, Num Lock, or Scroll Lock. This 
structure holds the settings and properties of ToggleKeys. 


cbSize 
The size in bytes of the structure. 
dwFlags 
Zero or more of the following flags specifying various settings and properties of ToggleKeys: 
TKF_AVAILABLE = &H2 
The ToggleKeys accessibility feature is available. 
TKF_CONFIRMHOTKEY = &H8 
Win 95/98 only: Open a confirmation dialog box when the user enables ToggleKeys via 
the hot key, 
TKF_HOTKEYACTIVE = &H4 
Enable the user to toggle ToggleKeys via the hot key: hold Num Lock for eight seconds. 
TKF_HOTKEYSOUND = &H10 
Play a sound when the user toggles ToggleKeys via the hot key. 
TKF_INDICATOR = &H20 
Win 95/98 only: Display an icon in the system tray while ToggleKeys is on. 
TKF_TOGGLEKEYSON = &H1 
ToggleKeys is currently on. 


Used by: SystemParametersInfo 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 


http://216.26.168.92/vbapi/ref/t/togglekeys.html (1 of 2) [9/1/2002 6:01:53 PM] 


Windows API Guide: TOGGLEKEYS Structure 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information. 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/t/togglekeys.html 


http://216.26.168.92/vbapi/ref/t/togglekeys.html (2 of 2) [9/1/2002 6:01:53 PM] 


Windows API Guide: TPMPARAMS Structure 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








TPMPARAMS Structure 


Type TPMPARAMS 
cbhSize As Long 
rcExclude As RECT 
End Type 


Description & Usage 


The TPMPARAMSS structure contains information needed to properly position a popup menu. Namely, 
this information consists of an exclusion rectangle. The exclusion rectangle is a rectangle on the screen 
which the popup menu is not allowed to cover. The popup menu's position will be adjusted in order to 
avoid the exclusion rectangle. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 

The size in bytes of the structure. 
rcExclude 

The coordinates of the exclusion rectangle. 


Used By 


TrackPopupMenuEx 


Back to the Structure list. 
Back to the Reference section. 
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ULARGE_INTEGER Structure 


Type ULARGE_INTEGER 
LowPart As Long 
HighPart As Long 

End Type 


Description & Usage 


The ULARGE_INTEGER structure stores a 64-bit unsigned integer. Unsigned integers range in value 
from &H0 to &HFFFFFFFFFFFFFFFF (or in decimal, 2%). This structure is defined primarily for 
languages (such as Visual Basic but including many others) which have no intrinsic support for 64-bit 
unsigned integers. The structure splits the value into two 32-bit halves: a high-order half and a low-order 
half. If the programming language you use does support 64-bit unsigned integers, you can replace the 
two data members of this structure with a single value (or use that data type instead of the structure 
altogether). 


Visual Basic-Specific Issues 


There is a way to use a variable of the Currency data type to represent a 64-bit integer. For more 
information, read the article "Faking 64-bit Integers." 


Data Members 


LowPart 

The 32-bit low-order half of the full 64-bit unsigned integer. 
HighPart 

The 32-bit high-order half of the full 64-bit unsigned integer. 


Used By 


GetDiskFreeSpaceEx, MEMORYSTATUSEX, SHQUERYRBINFO 
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Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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VS_FIXEDFILEINFO Structure 


Type VS_FIXEDFILEINFO 
dwSignature As Long 
dwStrucVersion As Long 
dwFileVersionMS As Long 
dwFileVersionLS As Long 
dwProductVersionMS As Long 
dwProductVersionLs As Long 
dwFileFlagsMask As Long 
dwFileFlags As Long 
dwFileOS As Long 
dwFileType As Long 
dwFileSubtype As Long 
dwFileDateMS As Long 
dwFileDateLS As Long 

End Type 


Description & Usage 


The VS_FIXEDFILEINFO structure holds version information that describes a 32-bit executable-type 
file. No version information strings are stored in the structure. 


Visual Basic-Specific Issues 


None. 


Data Members 


dwSignature 
The value & HFEEFO4BD. 
dwStrucVersion 
The version number of this structure. The high-order word holds the major version number, and 
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the low-order word holds the minor version number. 
dwFileVersionMS 
The high-order dword of the 64-bit version number. The high-order word of this dword is the 





leftmost component of the version number, and the low-order word is the number immediately to 
the right of it. (This is pretty much the major and minor version numbers of the file.) 
dwFileVersionLS 
The low-order dword of the 64-bit version number. The low-order word of this dword is the 
rightmost component of the version number, and the high-order dword is the component 
immediately to the left of it. (This is pretty much a major and minor revision number, if it is used 
at all.) 
dwProductVersionMS 
The high-order dword of the 64-bit version number of the product that the file was shipped with. 
The format of this value is the same as that of dwFileVersionMS. 
dwProductVersionLS 
The low-order dword of the 64-bit version number of the product that the file was shipped with. 
The format of this value is the same as that of dwFileVersionLsS. 
dwFileFlagsMask 
A bitmask that specifies what bits of dwFileFlags are valid. 
dwFileFlags 
A combination of the following flags specifying additional information about the file's version. 
Perform a bitwise And between this value and dwFileFlagsMask before checking for any of the 
following flags. 
VS_FF_DEBUG 
The file contains debugging information. 
VS_FF_INFOINFERRED 
The version information in this structure was not found inside the file, but instead was 
created when needed based on the best information available. Therefore, this structure's 
information may differ slightly from what the "real" values are. 
VS_FF_PATCHED 
The file has been modified somehow and is not identical to the original file that shipped 
with the product. 
VS_FF_PRERELEASE 
The file is a prerelease development version, not a final commercial release. 
VS_FF_PRIVATEBUILD 
The file was not built using standard release procedures. There should be data in the file's 
"PrivateBuild" version information string. 
VS_FF_SPECIALBUILD 
The file was built using standard release procedures, but is somehow different from the 
normal file having the same version number. There should be data in the file's 
"SpecialBuild" version information string. 
dwFileOS 
One of the following flags specifying the operating system which the file was meant to run on: 
VOS_DOS 
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The file was designed to run under MS-DOS. 
VOS_NT 
The file was designed to run under Windows NT/2000. 
VOS__WINDOWS16 
The file was designed to run under the 16-bit Windows API. 
VOS__WINDOWS32 
The file was designed to run under the 32-bit Windows API. 
VOS_OS216 
The file was designed to run under a 16-bit version of OS/2. 
VOS_OS232 
The file was designed to run under a 32-bit version of OS/2. 
VOS__PM16 
The file was designed to be run under a 16-bit version of Presentation Manager. 
VOS__PM32 
The file was designed to be run under a 32-bit version of Presentation Manager. 
VOS_UNKNOWN 
The operating system under which the file was designed to run could not be determined. 
dwFileType 
One of the following flags specifying the type of file this is: 
VFT_APP 
The file is an application. 
VFT_DLL 
The file is a Dynamic Link Library (DLL). 
VFT_DRV 
The file is a device driver. dwFileSubtype contains more information. 
VFT_FONT 
The file is a font. dwFileSubtype contains more information. 
VFT_STATIC_LIB 
The file is a static link library. 
VFT_VXD 
The file is a virtual device. 
VFT_UNKNOWN 
The type of file could not be determined. 
dwFileSubtype 
Specifies additional information about the file. The usage of this element of the structure depends 
on the value of dwFileType. 


If dwFileType is VFT_DRYV, then this is one of the following flags specifying the type of driver: 
VFT2_DRV_COMM 
The file is a communications driver. 
VFT2_DRV_DISPLAY 
The file is a display driver. 
VFT2_DRV_INSTALLABLE 
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The file is an installable driver. 
VFT2_DRV_KEYBOARD 

The file is a keyboard driver. 
VFT2_DRV_LANGUAGE 

The file is a language driver. 
VFT2_DRV_MOUSE 

The file is a mouse driver. 
VFT2_DRV_NETWORK 

The file is a network driver. 
VFT2_DRV_PRINTER 

The file is a printer driver. 
VFT2_DRV_SOUND 

The file is a sound driver. 
VFT2_DRV_SYSTEM 

The file is a system driver. 
VFT2_UNKNOWN 

The type of driver could not be determined. 


If dwFileType is VFT_FONT, then this is one of the following flags specifying the type of font: 


VFT2_FONT_RASTER 
The file is a raster font. 
VFT2_FONT_TRUETYPE 
The file is a TrueType font. 
VFT2_FONT_VECTOR 
The file is a vector font. 
VFT2_UNKNOWN 
The type of font could not be determined. 
dwFileDateMS 
The high-order dword of the file's 64-bit creation date and time stamp. 
dwFileDateLS 
The low-order dword of the file's 64-bit creation date and time stamp. 


Constant Definitions 


Const VS_FF_DEBUG = &H1 

Const VS_FF_INFOINFERRED = &H10 
Const VS_FF_PATCHED = &H4 

Const VS_FF_PRERELEASE = &H2 
Const VS_FF_PRIVATEBUILD = &H8 
Const VS_FF_PRIVATEBUILD = &H8 
Const VOS_DOS = &H10000 

Const VOS_NT = &H40000 
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Const 
Const 
Const 
Const 


VOS__WINDOWS16 = &H1 
VOS__WINDOWS32 = &H4 
VOS_0S216 = &H20000 
VOS_O0S232 = &H30000 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


Used By 


VerQuery Value 


VOS__PM16 = &H2 
VOS__PM32 &H3 
VOS_UNKNOWN = &HO 
VFT_APP = &H1 
VFT_DLL = &H2 
VFT_DRV = &H3 
VFT_FONT = &H4 
VFT STATIC LIB = 
VFT_VXD = &H5 
VFT_UNKNOWN = &HO 
VFT2_DRV_COMM = &HA 
VFT2_DRV_DISPLAY = &H4 
VFT2_DRV_INSTALLABLE = 
VFT2_DRV_KEYBOARD = &H2 
VFT2_DRV_LANGUAGE = &H3 
VFT2_DRV_MOUSE = &H5 
VFT2_DRV_NETWORK = &H6 
VFT2_DRV_PRINTER = &H1 
VFT2_DRV_SOUND = &H9 
VFT2_DRV_SYSTEM = &H7 
VFT2_FONT_RASTER = &H1 
VFT2_FONT_TRUETYPE = &H3 
VFT2_FONT_VECTOR = &H2 
VFT2_UNKNOWN = &HO 


&H7 


&H8 


Back to the Structure list. 
Back to the Reference section. 
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WAVEOUTCAPS Structure 


Type WAVEOUTCAPS 
wMid As Integer 
wPid As Integer 
vDriverVersion As Long 
szPname As String * 32 
dwFormats As Long 
wChannels As Integer 
dwSupport As Long 

End Type 


WAVEOUTCAPS-type variables store information about a waveform output device's capabilities as 
well as other information about it. The various members of the structure identify the abilities of the 
device. 


wMid 
The manufacturer identifier of the maker of the device. 
wPid 
The product identifier of the device. 
vDriverVersion 
The major and minor version numbers of the device. The high-order half of the value contains the 
major version number; the low-order half contains the minor version number. 
szPname 
A null-terminated string specifying the name of the device. 
dwFormats 
Zero or more of the following flags specifying the various audio output formats the device 
supports: 
WAVE_FORMAT_1IM08 = &H1 
Supports 11.025 kHz, 8-bit, mono playback. 
WAVE_FORMAT_1IM16 = &H4 
Supports 11.025 kHz, 16-bit, mono playback. 
WAVE_FORMAT_1S08 = &H2 
Supports 11.025 kHz, 8-bit, stereo playback. 
WAVE_FORMAT_1S16 = &H8 
Supports 11.025 kHz, 16-bit, stereo playback. 
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WAVE_FORMAT_2MO08 = &H10 

Supports 22.05 kHz, 8-bit, mono playback. 
WAVE_FORMAT_2M16 = &H40 

Supports 22.05 kHz, 16-bit, mono playback. 
WAVE_FORMAT_2S08 = &H20 

Supports 22.05 kHz, 8-bit, stereo playback. 
WAVE_FORMAT_2S16 = &H80 

Supports 22.05 kHz, 16-bit, stereo playback. 
WAVE_FORMAT_4M08 = &H100 

Supports 44.1 kHz, 8-bit, mono playback. 
WAVE_FORMAT_4M16 = &H400 

Supports 44.1 kHz, 16-bit, mono playback. 
WAVE_FORMAT_4S08 = &H200 

Supports 44.1 kHz, 8-bit, stereo playback. 
WAVE_FORMAT_4S16 = &H800 

Supports 44.1 kHz, 16-bit, stereo playback. 

wChannels 
The number of audio channels on the device. 1 means a mono device; 2 means a stereo device. 
dwSupport 

Zero or more of the following flags specifying which features the device supports: 
WAVECAPS_LRVOLUME = &H8 

Supports separate left and right channel volumes. 
WAVECAPS_PITCH = &H1 

Supports pitch control. 
WAVECAPS_PLAYBACKRATE = &H2 

Supports playback rate control. 
WAVECAPS_SAMPLEACCURATE = &H20 

Supports returning of sample-accurate position information. 
WAVECAPS_SYNC = &H10 

Supports synchronous playback -- i.e., it will block while playing buffered audio. 
WAVECAPS_VOLUME = &H4 

Supports volume control. 


Used by: waveOutGetDevCaps 


Go back to the alphabetical Structure listing. 
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WIN32 FIND DATA 


Type WIN32_FIND_DATA 
dwFileAttributes As Long 
ftCreationTime As FILETIME 
ftLastAccessTime As FILETIME 
ftLastWriteTime As FILETIME 
nFileSizeHigh As Long 
nFileSizeLow As Long 
dwReserved0 As Long 
dwReservedl As Long 
cFileName As String * 260 
cAlternate As String * 14 

End Type 


WIN32_FIND_DATA-type variables hold information found about a file from a file search operation. 
This information includes the file's attributes; its creation, last-access, and last-modified times; the size of 
the file; its long filename; and its short filename. The file size is a 64-bit value split into two halves of 32 
bits each: a high-order and a low-order half. The actual file size can be found by concatenating the binary 
or hexadecimal equivalents of the two halves. It can also be found by using the formula filesize = 
nFileSizeHigh * 2432 + nFileSizeLow. 


dwFileAttributes 

One or more of the following flags identifying the file's attributes: 
FILE_ATTRIBUTE_ARCHIVE = &H20 

An archive file (which most files are). 
FILE_ATTRIBUTE_COMPRESSED = &H800 

A file residing in a compressed drive or directory. 
FILE_ATTRIBUTE_DIRECTORY = &H10 

A directory instead of a file. 
FILE_ATTRIBUTE_HIDDEN = &H2 

A hidden file, not normally visible to the user. 
FILE_ATTRIBUTE_NORMAL = &H80 

An attribute-less file (cannot be combined with other attributes). 
FILE_ATTRIBUTE_READONLY = &H1 

A read-only file. 
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FILE_ATTRIBUTE_SYSTEM = &H4 
A system file, used exclusively by the operating system. 

ftCreationTime 

The time and date of when the file was created. 
ftLastAccessTime 

The time and date of when the file was last accessed. 
ftLastWriteTime 

The time and date of when the file was last modified or written to. 
nFileSizeHigh 

The high-order half of the file size. 
nFileSizeLow 

The low-order half of the file size. 
dwReservedO 

Reserved for future use. 
dwkReserved1 

Reserved for future use. 
cFileName 

The long filename of the file. 
cAlternate 

The short filename of the file. 


Used by: FindFirstFile, FindNextFile 
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WNDCLASS Structure 


Type WNDCLASS 
style As Long 
lpfnWndProc As Long 
cbClsExtra As Long 
cbWndExtra As Long 
hIinstance As Long 
hIcon As Long 
hCursor As Long 
hbrBackground As Long 
lpszMenuName As String 
lpszClassName As String 
End Type 


Description & Usage 


The WNDCLASS structure holds most of the information defining a window class. This information is 


used by any windows which belong to the class. The only item which this structure does not hold is a 
handle to the class's small icon. (The more advanced WNDCLASSEX structure does.) 


Visual Basic-Specific Issues 


None. 


Data Members 


style 
A combination of the following flags specifying various styles to give to windows which belong 
to the class: 
CS_BYTEALIGNCLIENT 
Align the window's client area horizontally on the byte boundary. 


CS_BYTEALIGNWINDOW 
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Align the window horizontally on the byte boundary. 
CS_CLASSDC 
Have all windows belonging to the class use a single shared device context used by all 
threads. 
CS_DBLCLKS 
Send a double-click message to the window procedure whenever the user double-clicks the 
mouse inside the window. 
CS_GLOBALCLASS 
Allow any application to create a window from this class. (If this flag is not specified, only 
the instance registering the class is allowed to use it.) The window class must be defined in 
a dynamic link library loaded at startup. 
CS_HREDRAW 
Redraw the entire window if a movement or size change alters the width of the window's 
client area. 
CS_NOCLOSE 
Disable the Close command on the window's menu. 
CS_OWNDC 
Give each window belonging to the class its own device context. 
CS_PARENTDC 
Set the clipping region of a child window equal to that of its parent window, allowing the 
child to draw on the parent. 
CS_SAVEBITS 
Save as a bitmap the portion of the screen image obscured by the window. This bitmap is 
then used to redraw the screen when the window is removed. Using this consumes more 
resources. 
CS_VREDRAW 
Redraw the entire window if a movement or size change alters the height of the window's 
client area. 
lpfnWndProc 
A pointer to the WindowProc hook function used for the window procedure which processes all 
of messages of each window belonging to the class. 
cbClsExtra 
The number of extra bytes to allocate following the window class structure for additional storage. 
cbWndExtra 
The number of extra bytes to allocate following the window instance structure for additional 
storage. 
hInstance 
A handle to the instance which contains the window procedure for the class. 
hIcon 
A handle to the window class's icon. 
hCursor 
A handle to the window class's cursor. 
hbrBackground 
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A handle to the brush used to fill the window's background area. This can also be one of the 
following flags specifying the system color to use as the background color: 
COLOR_ACTIVEBORDER 

The color of an active window's border. 
COLOR_ACTIVECAPTION 

The color of an active window's caption. 
COLOR_APPWORKSPACE 

The color of an application's workspace. 
COLOR_BACKGROUND 

The color of the desktop background. 
COLOR_BTNFACE 

The color of a button's face. 
COLOR_BTNHIGHLIGHT 

The color of a button's highlight area. 
COLOR_BTNSHADOW 

The color of a button's shadow area. 
COLOR_BTNTEXT 

The color of a button’s text. 
COLOR_CAPTIONTEXT 

The color of an active window's caption area's text. 
COLOR_GRAYTEXT 

The color of grayed-out text. 
COLOR_HIGHLIGHT 

The color of a highlight. 
COLOR_HIGHLIGHTTEXT 

The color of text in a highlight. 
COLOR_INACTIVEBORDER 

The color of an inactive window's border. 
COLOR_INACTIVECAPTION 

The color of an inactive window's caption. 
COLOR_INACTIVECAPTIONTEXT 

The color of an inactive window's caption area's text. 
COLOR_MENU 

The color of a menu. 
COLOR_MENUTEXT 

The color of a menu's text. 
COLOR_SCROLLBAR 

The color of a scrollbar. 
COLOR_WINDOW 

The color of a window. 
COLOR_WINDOWFRAME 

The color of a window's frame. 
COLOR_WINDOWTEXT 
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The color of a window's text. 
IpszMenuName 
The name of the window class's menu resource, if any. 
IpszClassName 
The name of the window class. 


Constant Definitions 


Const CS_BYTEALIGNCLIENT = &H1000 
Const CS_BYTEALIGNWINDOW = &H2000 


Const CS_CLASSDC = &H40 
Const CS _DBLCLKS = &H8 
Const CS _HREDRAW = &H2 


Const CS_NOCLOSE = &H200 
Const CS_OWNDC = &H20 

Const CS_PARENTDC = &H80 
Const CS_SAVEBITS = &H800 
Const CS_VREDRAW = &H1 

Const COLOR_ACTIVEBORDER = 10 
Const COLOR_ACTIVECAPTION = 2 


Const COLOR_APPWORKSPACE = 12 
Const COLOR_BACKGROUND = 1 
Const COLOR_BTNFACE = 15 
Const COLOR_BTNHIGHLIGHT = 20 


Const COLOR _BTNSHADOW = 16 
Const COLOR_BTINTEXT = 18 

Const COLOR_CAPTIONTEXT = 9 
Const COLOR_GRAYTEXT = 17 

Const COLOR_HIGHLIGHT = 13 
Const COLOR_HIGHLIGHTTEXT = 14 
Const COLOR_INACTIVEBORDER = 11 
Const COLOR_INACTIVECAPTION = 3 
Const COLOR_INACTIVECAPTIONTEXT = 19 
Const COLOR_MENU = 4 

Const COLOR_MENUTEXT = 7 

Const COLOR _SCROLLBAR = 0 

Const COLOR_WINDOW = 5 

Const COLOR_WINDOWFRAME = 6 
Const COLOR_WINDOWTEXT = 8 


Used By 
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GetClassInfo, RegisterClass 
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WNDCLASSEX Structure 


Type WNDCLASSEX 
cbhSize As Long 
style As Long 
lpfnWndProc As Long 
cbClsExtra As Long 
cbWndExtra As Long 
hInstance As Long 
hIcon As Long 
hCursor As Long 
hbrBackground As Long 
lpszMenuName As String 
lpszClassName As String 
hiconSm As Long 

End Type 


Description & Usage 


The WNDCLASSEX< structure holds all of the information defining a window class. This information is 
used by any windows which belong to the class. 


Visual Basic-Specific Issues 


None. 


Data Members 


cbSize 
The size in bytes of the structure. 

style 
A combination of the following flags specifying various styles to give to windows which belong 
to the class: 
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CS_BYTEALIGNCLIENT 
Align the window's client area horizontally on the byte boundary. 
CS_BYTEALIGNWINDOW 
Align the window horizontally on the byte boundary. 
CS_CLASSDC 
Have all windows belonging to the class use a single shared device context used by all 
threads. 
CS_DBLCLKS 
Send a double-click message to the window procedure whenever the user double-clicks the 
mouse inside the window. 
CS_GLOBALCLASS 
Allow any application to create a window from this class. (If this flag is not specified, only 
the instance registering the class is allowed to use it.) The window class must be defined in 
a dynamic link library loaded at startup. 
CS_HREDRAW 
Redraw the entire window if a movement or size change alters the width of the window's 
client area. 
CS_NOCLOSE 
Disable the Close command on the window's menu. 
CS_OWNDC 
Give each window belonging to the class its own device context. 
CS_PARENTDC 
Set the clipping region of a child window equal to that of its parent window, allowing the 
child to draw on the parent. 
CS_SAVEBITS 
Save as a bitmap the portion of the screen image obscured by the window. This bitmap is 
then used to redraw the screen when the window is removed. Using this consumes more 
resources. 
CS_VREDRAW 
Redraw the entire window if a movement or size change alters the height of the window's 
client area. 
lpfnWndProc 
A pointer to the WindowProc hook function used for the window procedure which processes all 
of messages of each window belonging to the class. 
cbClsExtra 
The number of extra bytes to allocate following the window class structure for additional storage. 
cbWndExtra 
The number of extra bytes to allocate following the window instance structure for additional 
storage. 
hInstance 
A handle to the instance which contains the window procedure for the class. 
hIcon 
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A handle to the window class's icon. 
hCursor 
A handle to the window class's cursor. 
hbrBackground 

A handle to the brush used to fill the window's background area. This can also be one of the 
following flags specifying the system color to use as the background color: 
COLOR_ACTIVEBORDER 

The color of an active window's border. 
COLOR_ACTIVECAPTION 

The color of an active window's caption. 
COLOR_APPWORKSPACE 

The color of an application's workspace. 
COLOR_BACKGROUND 

The color of the desktop background. 
COLOR_BTNFACE 

The color of a button's face. 
COLOR_BTNHIGHLIGHT 

The color of a button's highlight area. 
COLOR_BTNSHADOW 

The color of a button's shadow area. 
COLOR_BTNTEXT 

The color of a button’s text. 
COLOR_CAPTIONTEXT 

The color of an active window's caption area's text. 
COLOR_GRAYTEXT 

The color of grayed-out text. 
COLOR_HIGHLIGHT 

The color of a highlight. 
COLOR_HIGHLIGHTTEXT 

The color of text in a highlight. 
COLOR_INACTIVEBORDER 

The color of an inactive window's border. 
COLOR_INACTIVECAPTION 

The color of an inactive window's caption. 
COLOR_INACTIVECAPTIONTEXT 

The color of an inactive window's caption area's text. 
COLOR_MENU 

The color of a menu. 
COLOR_MENUTEXT 

The color of a menu's text. 
COLOR_SCROLLBAR 

The color of a scrollbar. 
COLOR_WINDOW 
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The color of a window. 
COLOR_WINDOWFRAME 
The color of a window's frame. 
COLOR_WINDOWTEXT 
The color of a window's text. 
lpszMenuName 
The name of the window class's menu resource, if any. 
IpszClassName 
The name of the window class. 
hIconSm 
A handle to the window class's small icon. 


Constant Definitions 


Const CS_BYTEALIGNCLIENT = &H1000 
Const CS_BYTEALIGNWINDOW = &H2000 


Const CS_CLASSDC = &H40 
Const CS _DBLCLKS = &H8 
Const CS _HREDRAW = &H2 


Const: .CS_NOCLOSE = &H200 
Const CS_OWNDC = &H20 

Const CS_PARENTDC = &H80 
Const CS SAVEBITS &H800 
Const CS_VREDRAW = &H1 

Const COLOR_ACTIVEBORDER = 10 
Const COLOR_ACTIVECAPTION = 2 


Const COLOR_APPWORKSPACE = 12 
Const COLOR_BACKGROUND = 1 
Const ‘COLOR. BINFACEK = 15 
Const COLOR _BTNHIGHLIGHT = 20 


Const COLOR _BTNSHADOW = 16 
Const COLOR_BTINTEXT = 18 

Const COLOR_CAPTIONTEXT = 9 
Const COLOR_GRAYTEXT = 17 

Const COLOR_HIGHLIGHT = 13 
Const COLOR_HIGHLIGHTTEXT = 14 
Const COLOR_INACTIVEBORDER = 11 
Const COLOR_INACTIVECAPTION = 3 
Const COLOR_INACTIVECAPTIONTEXT = 19 
Const COLOR_MENU = 4 

Const COLOR_MENUTEXT = 7 

Const COLOR _SCROLLBAR = 0 
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Const COLOR_WINDOW = 5 
Const COLOR_WINDOWFRAME = 6 
Const COLOR_WINDOWTEXT = 8 


Used By 


GetClassInfoEx, RegisterClassEx 


Go back to the alphabetical Structure listing. 
Go back to the Reference section index. 
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WSADATA Structure 


Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szsystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendoriInfo As Long 

End Type 


Description & Usage 


The WSADATA structure stores information about the Windows Sockets (Winsock) implementation 
being used by your program. Most of the structure's contents refer to the version of Winsock the program 
is interfacing with. 


Visual Basic-Specific Issues 


None. 


Data Members 


wVersion 
The version of Winsock that Windows expects you to use. The low-order byte contains the major 
version number, and the high-order byte contains the minor version number. This should be the 
same version you specified when calling WSAStartup. 

wHighVersion 
The highest version of Winsock that Windows supports. The version number is encoded in the 
same manner as wVersion. 

szDescription 
A null-terminated string that describes the Winsock implementation being used. 
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szSystemStatus 
A null-terminated string specifying the Winsock implementation's current status. 

iMaxSockets 
Not used -- this member exists solely for backwards compatibility with Winsock version 1.1 and 
earlier. 

iMaxUdpDg 
Not used -- this member exists solely for backwards compatibility with Winsock version 1.1 and 
earlier. 

lp VenderInfo 
Not used -- this member exists solely for backwards compatibility with Winsock version 1.1 and 
earlier. 


Used By 


WSAStartup 


Back to the Structure list. 
Back to the Reference section. 


Last Modified: October 29, 2000 
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Windows API Reference: Messages 


Last Update: January 21, 2001 
Number of Messages Listed: 66 (6 added) 


Below is a categorical list of the API messages currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to: 


e Buttons 

e Combo Boxes 

e Edit Controls 

e IP Address Control 

e List Boxes 

e Media Control Interface (MCI) 
e Menus 

e Mouse 

e Timers 

e Windows 


e Buttons 
o BM_CLICK 
o BM_GETCHECK 
o BM_GETSTATE 
o BM _SETCHECK 
o BM_SETSTATE 
e Combo Boxes 
o CB_ADDSTRING 
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o CB_DELETESTRING 
o CB_GETCOUNT 
o CB_GETCURSEL 
o CB_GETDROPPEDSTATE 
o CB_GETLBTEXT 
o CB_GETLBTEXTLEN 
o CB_INSERTSTRING 
o CB _RESETCONTENT 
o CB _SETCURSEL 
o CB_SHOWDROPDOWN 
e Edit Controls 
o EM_CANUNDO 
o EM_GETFIRSTVISIBLELINE 
o EM_GETLINE 
o EM_GETPASSWORDCHAR 
o EM_GETSEL 
o EM_LINEINDEX 
o EM_LINELENGTH 
o EM _REPLACESEL 
o EM_SETPASSWORDCHAR 
o EM_SETSEL 
o EM_ UNDO 
e IP Address Control 
o IPM _CLEARADDRESS 
o IPM_GETADDRESS 
o IPM _ISBLANK 
o IPM_SETADDRESS 
o IPM_SETFOCUS 
o IPM SETRANGE 
e List Boxes 
o LB_ADDSTRING 
o LB_DELETESTRING 
o LB_GETCOUNT 
o LB_GETCURSEL NEW 
o LB_GETSEL NEW 
o LB_GETSELCOUNT NEW 
o LB_GETSELITEMS NEW 
o LB_GETTEXT 
o LB_GETTEXTLEN 
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o LB_INSERTSTRING 
o LB_RESETCONTENT 
o LB _SETCURSEL NEW 
o LB_SETSEL NEW 

e Media Control Interface (MCI) 
o MM MCINOTIFY 


e Menus 
o WM COMMAND 
o WM_INITMENU 
o WM_SYSCOMMAND 

e Mouse 
o WM _LBUTTONDBLCLK 
o WM_LBUTTONDOWN 
o WM_LBUTTONUP 
o WM _MBUTTONDBLCLK 
o WM_MBUTTONDOWN 
o WM_MBUTTONUP 
o WM MOUSEMOVE 
o WM_RBUTTONDBLCLK 
o WM_RBUTTONDOWN 
o WM _RBUTTONUP 

e Timers 
o WM_TIMER 

e Windows 
o WM_CLOSE 
o WM_GETTEXT 
o WM_GETTEXTLENGTH 
o WM_HELP 
o WM_SETTEXT 


Go back to the Reference section index. 


Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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BM_ CLICK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.5 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the BM_CLICK message to a button simulates the user clicking on that button. Sometimes this message will not 
work if the button's parent window is not active. To avoid this, use SetActiveWindow to make its parent window active before 
sending this message. 


Return Value 


This message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const BM CLICK = &HF5 











Example 


This code uses a Timer object to periodically check for a dialog box to appear. If found, the code uses BM_CLICK to "click" 
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the button labeled "Resume" to close the dialog box. Something akin to this code might make a nifty way to automatically 
clear out those annoying "Are you still online?" dialog boxes that some ISP connection programs open every 45 minutes or so. 
To use this code, place a timer control named Timer! in a window and give it a period of something like 10000 (every 10 


seconds). 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
"user32.dll1" Alias "SendMessageA" (ByVal hWnd 


Public 


Public 
Public 
Public 


Public 


' ***x Place the following code in the 
Private Sub Timerl_Timer() 


open. 





End Sub 





Declare Function SendMessage Lib 








As Long, ByVal Msg As Long, wParam As Any, 


Const BM CLICK = &HF5 














Declare Function FindWindowEx Lib 
hwndParent As Long, ByVal hwndCh 
ByVal lpszWindow As Any) As Long 











E 














Dim hwndDialog As Long ' handle 
Dim hwndButton As Long ' handle 
Dim retval As Long ' return 








Declare Function SetActiveWindow Lib 


lParam As Any) 








Declare Function FindWindow Lib "user32.d11" 








As Long 


"user32.dl11" (ByVal hWnd As Long) As Long 





Alias "FindWindowA" (ByVal _ 





lpClassName As Any, ByVal lpWindowName As Any) As Long 











"user32.dl1" Alias "FindWindowExA" (ByVal _ 





ildAfter As Long, 








form. *** 





value 








to the dialog box 
to the Resume button 





ByVal lpszClass As Any, 





' First, see if the dialog box (titled "Inactivity Warning" is currently 


hwndDialog = FindWindow (CLng (0), 
If hwndDialog = 0 Then Exit Sub 











"Inactivity Warning") 


' Now get a handle to the "Resume" button in the dialog. 





hwndButton = FindWindowEx(hwndDialog, 0, CLng (0), 














' After making sure that the dia 
retval = SetActiveWindow (hwndDia 




















retval = SendMessage (hwndButton, 





Category 


Buttons 


Back to the Messagelist. 





Back to the Reference section. 





Last Modified: October 29, 2000 
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ByVal CLng (0), 


"Resume") 


the active window, click "Resume". 





ByVal CLng(0)) 
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Go back to the Windows API Guide home page. 
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BM_GETCHECK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the BM_GETCHECK message to a button determines if that button is currently checked. Obviously, this message 
only works with buttons that are check boxes or radio boxes. 


Return Value 


If an error occured, the message returns zero. Otherwise, the message returns one of the following values specifying the 
button's checked state: 


BST_CHECKED 

The button is checked. 
BST_INDETERMINATE 

The button is grayed, in an indeterminate state. This only works with check boxes that have three possible states. 
BST_UNCHECKED 

The button is unchecked. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 
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Const BM_GETCHECK = &HFO 
Const BST_CHECKED = 6&1 

Const BST_INDETERMINATE = &2 
Const BST_UNCHECKED = &0 




















T 









































Example 


Use the BM_GETCHECK message to determine the checked status of check box Check1 when a button is pressed. To run 
this example, you need to create a check box control named Check1 and a command button named Command] in a form 
window. The check box may be any type you wish. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 














As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const BM_GETCHECK = &HFO 
Public Const BST_CHECKED = &1 
Public Const BST_INDETERMINATE = &2 
Public Const BST_UNCHECKED = &0 























T 






































' *** Place the following code inside the form window. *** 
Private Sub Command1_Click () 
Dim state As Long ' checked state of the check box 


























' Find the checked state of Checkl and tell the user what it is. 

state = SendMessage(Checkl.hWnd, BM_GETCHECK, ByVal CLng(0), ByVal CLng (0)) 
Select Case state 

Case BST_CHECKED 
Debug.Print "The check box is checked." 
Case BST_INDETERMINATE 
Debug.Print "The check box is in its third state (grayed) ." 
Case BST_UNCHECKED 
Debug.Print "The check box is not checked." 
End Select 







































































End Sub 





See Also 


BM_GETSTATE, BM_SETCHECK 


Category 


Buttons 


Back to the Function list. 
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Back to the Reference section. 
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BM_GETSTATE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the BM_GETSTATE message to a button retrieves information about the state of the button. This message works 
will all types of buttons, including command buttons, check boxes, and radio buttons. 


Return Value 


If an error occured, the message returns zero. Otherwise, the message returns a combination of the following values specifying 
the button's current state: 


BST_CHECKED 
The button is checked. 
BST_FOCUS 
The button has the keyboard focus. 
BST_INDETERMINATE 
The button is grayed, in an indeterminate state. This only works with check boxes that have three possible states. 
BST_PUSHED 
The button is being pushed. This is typically caused by the left button being held down on top of the button, making it 
look pushed in. 
BST_UNCHECKED 
The button is unchecked. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
Not used -- set to 0. 
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lParam 


Not used -- set to 0. 


Constant Definitions 

























































































Const BM_GETSTATE = &HF2 
Const BST_CHECKED = &H1 

Const BST_FOCUS = &H8 

Const BST_INDETERMINATE = &H2 
Const BST_PUSHED = &H4 

Const BST_UNCHECKED = &H0O 
Example 


Use the BM_GETSTATE message to determine the state of check box Check1 when a button is pressed. To run this example, 
you need to create a check box control named Check1 and a command button named Command 1 in a form window. The check 
box may be any type you wish. 


F 


This 


' 





Decla 


(Copy 
Public 


ublic 
ub 
ubl 
ub] 
ubl 
ublic 


lic 


ic 
lic 


ic 


U. g ty tg ty tg 








' KkK* P 


Private 


focus." 


End Sub 





http://216. 


code is licensed according to the terms and conditions listed here. 









































































































































































































































rations and such needed for the example: 
them to the (declarations) section of a module.) 
Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Const BM_GETSTATE = &HF2 
Const BST_CHECKED = &H1 
Const BST FOCUS = &H8 
Const BST_INDETERMINATE = &H2 
Const BST PUSHED = &H4 
Const BST_UNCHECKED = &HO 
lace the following code inside the form window. *** 
Sub Commandi1_Click () 
Dim state As Long ' checked state of the check box 
' Find the state of Checkl and tell the user what it is. 
state = SendMessage(Checkl.hWnd, BM_GETSTATE, ByVal CLng(0), ByVal CLng (0)) 
If state And BST_CHECK Then 
Debug.Print "The check box is checked." 
ElseIf state And BST_INDETERMINATE Then 
Debug.Print "The check box is in its third state (grayed) ." 
Else 
Debug.Print "The check box is not checked." 
End If 
If state And BST_FOCUS Then Debug.Print "The check box has the keyboard 
If state And BST_PUSHED Then Debug.Print "The check box is being pushed." 
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See Also 


BM_GETCHECK, BM_SETSTATE 














Category 


Buttons 


Back to the Function list. 
Back to the Reference section. 





Last Modified: July 30, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/b/bm_getstate.htm] 











http://216.26.168.92/vbapi/ref/b/bm_getstate.html (3 of 3) [9/1/2002 6:05:24 PM] 


Windows API Guide: BM_SETCHECK Message 
vbapi.com - part of the VB-World Network 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





BM_SETCHECK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


WHITE | CLIFF 


Sending the BM_SETCHECK message to a button changes the checked state of a button. Naturally, the button has to be 
either a check box or a radio button for the message to work. The message can check or uncheck the button. If the button is a 


three-state check box, the message can also put the button into its third, grayed state. 


Return Value 


The BM_SETCHECK message always returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
One of the following flags specifying how to set the button's checked state: 
BST_CHECKED 
Check the button. 
BST_INDETERMINATE 


Put the button into its third, grayed state. This only works for three-state check boxes. 


BST_UNCHECKED 
Uncheck the button. 
lParam 
Not used -- set to 0. 


Constant Definitions 
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Const BM_SETCHECK = &HF1 
Const BST_CHECKED = &1 

Const BST_INDETERMINATE = &2 
Const BST_UNCHECKED = &0 



























































Example 


Use the BM_SETCHECK message to place a check mark inside of Check1. Do this when a button is pressed. To run this 
example, place a check box control named Check! and a command button named Command 1 inside a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 








Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" 





~ 


As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 











Public Const BM_SETCHECK = &HF1 
Public Const BST_CHECKED = &1 
Public Const BST_INDETERMINATE = &2 
Public Const BST_UNCHECKED = &0 













































































' ***x Place the following code inside the form window. *** 
Private Sub Commandl1_Click () 
Dim retval As Long ' return value 














' Place a check mark inside Checkl. 





ByVal hWnd 




















retval = SendMessage(Check1l.hWnd, BM_SETCHECK, ByVal CLng(BST_CH 
CLng (0) ) 

' That's it! 
End Sub 
See Also 


BM_GETCHECK, BM_SETSTATE 


Category 


Buttons 


Back to the Function list. 
Back to the Reference section. 
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ECKE] 











ByVal 
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BM_SETSTATE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the BM_SETSTATE message changes the pushed state of a button. This message allows you to control whether a 
button looks pushed down or not. The appearance of the button has no other effect on its state or checked/unchecked value, if 
applicable. In reality, this message only affects command buttons. 


Return Value 


The BM_SETSTATE message always returns 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
If this is a non-zero value, the button's appearance is changed to make it looked pushed down. If this is zero, the 
button's appearance is changed to make it look normal. 

lParam 
Not used -- set to 0. 


Example 


Use the BM_SETSTATE message to make button Command! look pressed down. Do this when the user clicks on button 
Command2. Obviously, to use this example, you need to make two command buttons named Command! and Command2 on a 
form window. 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 








Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 

















Public Const BM_SETSTATE = é&HF4 





' *** Place the following code inside the form window. *** 
Private Sub Command2_Click () 
Dim retval As Long ' return value 





' Make button Commandl look pressed down. 














retval = SendMessage(Checkl.hWnd, BM_SETSTATE, ByVal CLng ( 
' That's it! 

End Sub 

See Also 


BM_GETSTATE, BM_SETCHECK 


Category 


Buttons 


Back to the Function list. 
Back to the Reference section. 
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CB_ADDSTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_ADDSTRING message to a combo box control adds a string to the control's drop-down list. If the combo box 
is sorted, the new string is added in its proper position according to the sort. If the combo box is not sorted, the new string is 
added to the end. To control where the string is added, use the CB_INSERTSTRING message instead. 








Return Value 


If successful, the message returns the zero-based index of the newly added string's position in the combo box's drop-down box. 
If there is insufficient space to store the new string, the message returns CB_ERRSTRING. If some other error occurs, the 
message returns CB_ERR. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


The string to add to the combo box's drop-down box. 


Constant Definitions 








Const CB_ADDSTRING = &H143 
Const CB_ERR = -1 
Const CB _ERRSPACE = -2 
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Example 


When the user clicks button Command1, empty the drop-down box of combo box Combol, and then add three strings to it. 
The order in which the strings appear will depend on whether the combo box is sorted or not. 


To use this example, place a combo box named Combo1 and a command button named Command! on a form window. To 
verify that the combo box's list is being emptied, you may wish to add some items to it before running the example. 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_ADDSTRING = &H143 


Public Const CB RESETCONTENT = &H14B 















































' ***x Place the following code inside a form window. *** 





Private Sub Command1_Click () 
Dim retval As Long ' return value 











' Empty the drop-down box of Combol. 
retval = SendMessage(Combol.hWnd, CB RESETCONTENT, ByVal CLng(0), ByVal 
CLng (0) ) 






































' Now add three strings to Combol. Their exact placement will 

' depend on whether Combol is sorted or not. 

retval = SendMessage(Combol.hWnd, CB_ADDSTRING, ByVal CLng(0), ByVal "First 
Item Added") 
retval = SendMessage(Combol.hWnd, CB_ADDSTRING, ByVal CLng(0), ByVal "Second 
Item Added") 
retval = SendMessage(Combol.hWnd, CB_ADDSTRING, ByVal CLng(0), ByVal "Last 
Item Added") 
End Sub 






























































See Also 


CB_DELETESTRING, CB_INSERTSTRING, CB_RESETCONTENT 














Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB DELETESTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_DELETESTRING message to a combo box removes one of the items from its drop-down box. 


Return Value 


If successful, the message returns the number of items remaining in the combo box's drop-down box. If an error occured, the 
message returns CB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the string to delete from the combo box's drop-down box. 
lParam 

Not used -- set to zero. 


Constant Definitions 



































Const CB _DELETESTRING = &H144 
Const CB_ERR = -1 
Example 


When the user clicks button Command 1, remove the second item from combo box's Combo1 drop-down box. To run this 
example, place a combo box named Combo1 and a command button named Command1 on a form window. 
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Windows API Guide: CB_DELETESTRING Message 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_DELETESTRING = &H144 
Public Const CB_ERR = -l 

















' *** Place the following code inside a form window. *** 


Private Sub Command1_Click () 
Dim result As Long ' result of string deletion attempt 








' Remove the second item from Combol's drop-down list 
' box, and display the result. 
result = SendMessage(Combol.hWnd, CB_DELETESTRING, ByVal CLng(1), ByVal 

































































CLng (0) ) 
If result = CB_ERR Then 
Debug.Print "Unable to delete the second string in Combol's drop-down 
box." 
Else 
Debug.Print "There are"; result; "strings left in Combol's drop-down 
box." 
End If 
End Sub 





See Also 


CB_ADDSTRING, CB_INSERTSTRING, CB_RESETCONTENT 

















Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB _GETCOUNT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_GETCOUNT message determines how many items exist in the list box portion of a combo box control. Keep 
in mind that the list box items are zero-based; the first item has an index of zero, and the last one has an index of the count 
minus one. 


Return Value 


If successful, the message returns the number of items that are in the list box portion of a combo box control. If an error 
occured, the message returns -1. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const CB _GETCOUNT = &H146 











Example 
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Windows API Guide: CB_GETCOUNT Message 
' This code is licensed according to the terms and conditions listed here. 
' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" 











~ 


ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_GETCOUNT = &H146 
Public Const CB_GETLBTEXT = &H148 
Public Const CB GETLBTEXTLEN = &H149 

































































' Display the text of the second-to-last item in the list box portion 
' of combo box Combol. 

Dim count As Long " number of items in the combo box 

Dim s21 As Long ' index of the second-to-last item 

Dim itemtext As String ' text of that item 

Dim textlen As Long ' length of the item text 











' Figure out the index of the second-to-last item by subtracting two from 
' the total item count (remember, the index is zero-based). 
count = SendMessage (Combol.hWnd, CB_GETCOUNT, ByVal CLng(0), ByVal CLng(0)) 


s2l = count - 2 














' Make the string long enough to receive that item's text. 

textlen = SendMessage(Combol.hWnd, CB GETLBTEXTLEN, ByVal s21, ByVal CLng(0)) 
itemtext = Space(textlen) & vbNullChar 

' Get the item text and remove the trailing null. 

textlen = SendMessage(Combol.hWnd, CB GETLBTEXT, ByVal s21, ByVal itemtext) 
itemtext Left (itemtext, textlen) 

Finally, display the result. 

Debug.Print "The second-to-last item is "; itemtext 








































































































Category 


Combo Boxes 
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CB GETCURSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The CB_GETCURSEL message finds out which list-box item is currently selected in a combo box control. This message 
only returns useful information if the combo box's selection is one of the items available in its list box portion. If the user types 
different data into the tex box portion, the function merely reports that no item is selected. 


Return Value 


The message returns the zero-based index of the selected item (the first item has an index of 0, etc.). If none of the items in the 
list box portion are selected, the message returns -1. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const CB_GETCURSEL = &H147 














Example 
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Windows API Guide: CB_GETCURSEL Message 
' This code is licensed according to the terms and conditions listed here. 
' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1l1" Alias "SendMessageA" 











~ 


ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_GETCURSEL = &H147 
Public Const CB_GETLBTEXT = &H148 
Public Const CB GETLBTEXTLEN = &H149 

















































































































' Display the text of whatever item in combo box Combol 

' is currently selected. If no list box item is selected, say so. 
Dim index As Long ' index to the selected item 
Dim itemtext As String ' the text of the selected item 
Dim textlen As Long ' the length of the selected item's text 

' Determine the index of the selected item. 

index = SendMessage (Combol.hWnd, CB_GETCURSEL, ByVal CLng(0), ByVal CLng(0)) 
' Decide what to do based on that. 











Select Case index 





Case -1 ' No list box item was selected. 
Debug.Print "No list box item in the combo box is selected." 
Case Else ' Some item is selected. 








" Determine how long the item's text is. 
textlen = SendMessage (Combol.hWnd, CB GETLBTEXTLEN, ByVal CLng (index), ByVal 



































CLng (0) ) 














' Make enough room in the string to receive the text, including the 
terminating null. 

itemtext = Space (textlen) & vbNullChar 

' Retrieve that item's text and display it. 

textlen = SendMessage (Combol.hWnd, CB GETLBTEXT, ByVal CLng(index), ByVal 
itemtext) 
itemtext = Left (itemtext, textlen) 
Debug.Print "Selected item: "; itemtext 
End Select 





















































See Also 


CB_SETCURSEL 


Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB_GETDROPPEDSTATE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_GETDROPPEDSTATE message to a combo box determines if its list box portion is currently visible. In 
most combo boxes, the list box can be either dropped down or hidden. This message only works if the combo box has that 
capability. 


Return Value 


If the message returns 0, the list box portion is currently hidden. If the message returns a non-zero value, the list box is visible. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 


























Const CB_GETDROPPEDSTATE = &H157 


Example 


' This code is licensed according to the terms and conditions listed here. 
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Windows API Guide: CB_GETDROPPEDSTATE Message 


' Declarations and such needed 





for the example: 





' (Copy them to the (declarations) section of a module.) 


Public Declare Function SendMessage Lib "user32.d11" Alias 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) 
Public Const CB_GETDROPPEDSTATE 








' Determine if the list box of 
' in its dropped down, visible 
Dim isdropped As Long ' is it 














isdropped = SendMessage (Combol 
CLng (0) ) 

Select Case isdropped 

Case 0 





Debug.Print "The list 
Case Else 
Debug.Print "The list 
End Select 














See Also 


CB_SHOWDROPDOWN 





Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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state. 
dropped down or not? 
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As Long 
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CB_GETLBTEXT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The CB_GETLBTEXT message retrieves the text of one of the items in the list box portion of a combo box control. 


Return Value 


If successful, the message returns the length of the string copied into the string passed as /Param, not including the terminating 
null character. If an error occured, the message returns -1. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the list box item to retrieve the text of. (The first item has an index of 0, etc.) 

lParam 
The string to copy the list box item text into. The string must have enough room to receive the entire string along with a 
terminating null character. 


Constant Definitions 




















Const CB_GETLBTEXT = &H148 


Example 


' This code is licensed according to the terms and conditions listed here. 
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Windows API Guide: CB_GETLBTEXT Message 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB GETCURSEL = &H147 
Public Const CB_GETLBTEXT = &H148 
Public Const CB _GETLBTEXTLEN = &H149 






























































' Display the text of whatever item in combo box Combol 
































' is currently selected. If no list box item is selected, say so. 
Dim index As Long ' index to the selected item 

Dim itemtext As String ' the text of the selected item 

Dim textlen As Long " the length of the selected item's text 














' Determine the index of the selected item. 

index = SendMessage(Combol.hWnd, CB GETCURSEL, ByVal CLng(0), ByVal CLng(0) ) 
' Decide what to do based on that. 

Select Case index 





















































Case -1 ' No list box item was selected. 

Debug.Print "No list box item in the combo box is selected." 
Case Else ' Some item is selected. 

' Determine how long the item's text is. 





























textlen = SendMessage (Combol.hWnd, CB GETLBTEXTLEN, ByVal CLng (index), ByVal 











CLng (0) ) 














' Make enough room in the string to receive the text, including the 
terminating null. 

itemtext = Space (textlen) & vbNullChar 

' Retrieve that item's text and display it. 

textlen = SendMessage (Combol.hWnd, CB_GETLBTEXT, ByVal CLng(index), ByVal 
itemtext) 
itemtext = Left (itemtext, textlen) 
Debug.Print "Selected item: "; itemtext 
End Select 
































See Also 


CB_GETLBTEXTLEN 


Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB_GETLBTEXTLEN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The CB_GETLBTEXTLEN message retrieves the length of the text of one of the items in the list box portion of a combo box 
control. The reported length does not include its terminating null character. When determining how long to size a string to 
receive the list box item's text, remember to add one to include the null. 


Return Value 


If successful, the message returns the length of the list box item's text, not including the terminating null character. If an error 
occured, the message returns -1. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the list box item to retrieve the length of the text of. (The first item has an index of 0, etc.) 
lParam 

Not used -- set to 0. 


Constant Definitions 





Const CB _GETLBTEXTLEN = &H149 




















Example 
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Windows API Guide: CB_GETLBTEXTLEN Message 
' This code is licensed according to the terms and conditions listed here. 
' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" 











~ 


ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB GETCURSEL = &H147 
Public Const CB GETLBTEXT = &H148 
Public Const CB_GETLBTEXTLEN = &H149 









































































































































" Display the text of whatever item in combo box Combol 

' is currently selected. If no list box item is selected, say so. 
Dim index As Long ' index to the selected item 
Dim itemtext As String ' the text of the selected item 
Dim textlen As Long ' the length of the selected item's text 

" Determine the index of the selected item. 

index = SendMessage(Combol.hWnd, CB GETCURSEL, ByVal CLng(0), ByVal CLng(0) ) 
' Decide what to do based on that. 











Select Case index 





Case -1 ' No list box item was selected. 
Debug.Print "No list box item in the combo box is selected." 
Case Else ' Some item is selected. 








" Determine how long the item's text is. 

textlen = SendMessage (Combol.hWnd, CB_GETLBTEXTLEN, ByVal CLng(index), ByVal 
CLng (0) ) 

' Make enough room in the string to receive the text, including the 
terminating null. 

itemtext = Space (textlen) & vbNullChar 

' Retrieve that item's text and display it. 

textlen = SendMessage (Combol.hWnd, CB GETLBTEXT, ByVal CLng (index), ByVal 
itemtext) 
itemtext = Left (itemtext, textlen) 
Debug.Print "Selected item: "; itemtext 
End Select 







































































See Also 


CB_GETLBTEXT 


Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB_INSERTSTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_INSERTSTRING message to a combo box inserts a string into its drop-down box. The string is placed at the 
position specified in the parameters, regardless of whether the combo box is sorted or not. 


Return Value 


If successful, the message returns the zero-based index of the newly added string's position in the combo box's drop-down box. 
If there is insufficient space to store the new string, the message returns CB_ERRSTRING. If some other error occurs, the 
message returns CB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the position to insert the string in the combo box's drop-down box. If this is -1, the string is 
added to the end of the list. 

lParam 
The string to add to the combo box's drop-down box. 


Constant Definitions 























Const CB_INSERTSTRING = &H14A 
Const CB_ERR = -1 
Const CB _ERRSPACE = -2 
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Example 


When the user clicks button Command 1, insert three strings into combo box Combol's drop-down box. One string is added to 
the beginning, one to the third position, and one to the end. To run this example, place a combo box named Combol and a 
command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_INSERTSTRING = &H14A 




















' ***x Place the following code inside a form window. *** 





Private Sub Command1l_Click () 
Dim retval As Long ' return value 








' Add a string to the beginning of the drop-down box. 
retval = SendMessage(Combol.hWnd, CB_INSERTSTRING, ByVal CLng(0), ByVal 
"First Item") 


' 

















Insert a string at the third position in the drop-down box. 

retval = SendMessage(Combol.hWnd, CB_INSERTSTRING, ByVal CLng(2), ByVal 
"Third Item") 

' Add a string to the end of the drop-down box. 

retval = SendMessage(Combol.hWnd, CB_INSERTSTRING, ByVal CLng(-1), ByVal 
"Last Item") 
End Sub 









































See Also 


CB_ADDSTRING, CB_DELETESTRING, CB_RESETCONTENT 


Category 


Combo Boxes 


Back to the Message list. 





Back to the Reference section. 


Last Modified: September 24, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 
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CB RESETCONTENT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB_RESETCONTENT message to a combo box removes all the items from its drop-down box and edit control. 


Return Value 


This message always returns zero. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const CB _RESETCONTENT = &H14B 




















Example 


When the user clicks button Command 1, empty the drop-down box of combo box Combol, and then add three strings to it. 
The order in which the strings appear will depend on whether the combo box is sorted or not. 
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To use this example, place a combo box named Combo1 and a command button named Command! on a form window. To 
verify that the combo box's list is being emptied, you may wish to add some items to it before running the example. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" ( 














As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 

Public Const CB ADDSTRING = &H143 

Public Const CB_RESETCONTENT = &H14B 























' xxx Place the following code inside a form window. *** 








Private Sub Command1_Click () 
Dim retval As Long ' return value 





' Empty the drop-down box of Combol. 








ByVal hWnd 


retval = SendMessage(Combol.hWnd, CB_RESETCONTENT, ByVal CLng(0), ByVal 








































































































CLng (0) ) 

' Now add three strings to Combol. Their exact placement will 

' depend on whether Combol is sorted or not. 

retval = SendMessage(Combol.hWnd, CB ADDSTRING, ByVal CLng(0), ByVal "First 
Item Added") 

retval = SendMessage(Combol.hWnd, CB ADDSTRING, ByVal CLng(0), ByVal "Second 
Item Added") 

retval = SendMessage(Combol.hWnd, CB ADDSTRING, ByVal CLng(0), ByVal "Last 
Item Added") 
End Sub 





See Also 


CB_ADDSTRING, CB_DELETESTRING, CB_INSERTSTRING 




















Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 





Last Modified: Month DD, 2000 
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CB SETCURSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The CB_SETCURSEL message chooses which item in the list box portion of a combo box control is selected. Doing so 
erases the user's previous selection, as well as any other text he may have entered in the text box portion of the control. 


Return Value 


The message returns the zero-based index of the item that is now selected (the first item has an index of 0, etc.). If an error 
occured, or if the message specified a list box item that does not exist, the message returns -1. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the list box item to select. 
lParam 

Not used -- set to 0. 


Constant Definitions 





Const CB_SETCURSEL = &H14E 

















Example 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 














As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_SETCURSEL = &H14E 








' Select the second item (index 1) available in the list box portion of the combo 
' box control Combol. 
Dim retval As Long ' return value of message 














' Change the current selection of Combol. 
retval = SendMessage(Combol.hWnd, CB_SETCURSEL, ByVal CLng(1), ByVal CLng(0) ) 

















See Also 


CB_GETCURSEL 








Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 
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CB_SHOWDROPDOWN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the CB SHOWDROPDOWN message to a combo box opens or closes its drop-down list box section. Naturally, this 
message only works if the combo box has a list that can be dropped down, instead of always or never displaying it. 


Return Value 


This message always returns a non-zero value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

If zero, closes the drop-down list of the combo box. If non-zero, opens the drop-down list of the combo box. 
lParam 

Not used -- set to 0. 


Constant Definitions 


Const CB_SHOWDROPDOWN = &H14F 











Example 


' 


This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 


http://216.26.168.92/vbapi/ref/c/cb_showdropdown.html (1 of 2) [9/1/2002 6:06:27 PM] 


Windows API Guide: CB_SHOWDROPDOWN Message 





' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 














As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const CB_SHOWDROPDOWN = &H14F 





' Display the drop-down list box of combo box Combol. 
Dim retval As Long ' return value 








retval = SendMessage(Combol.hWnd, CB_SHOWDROPDOWN, ByVal CLng(1), ByVal CLng(0) ) 

















See Also 


CB_GETDROPPEDSTATE 


Category 


Combo Boxes 


Back to the Message list. 
Back to the Reference section. 


Last Modified: April 16, 2000 
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EM CANUNDO Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_CANUNDO message to an edit control determines if the last operation can be undone. If an undo is allowed, 
the user can select "Undo" from the control's context menu, and the EM_UNDO message can also be sent to perform an undo. 


Return Value 


If an undo operation is valid, the function returns a nonzero value. If no undo is possible, the function returns 0. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 


Const EM_CANUNDO = &HC6 








Example 


Demonstrate undo operations for an edit control. Place three controls on a form window: an edit control (text box) named 
txtBox, a command button named cmdUndo, and another command button named cmdSet. Pressing cmdSet sets the contents 
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of txtBox to a predetermined string, a change that cannot be undone. Pressing cmdUndo, naturally, undoes the last change 
made by the user to txtBox. Whenever the contents of txtBox change, the enabled status of cmdUndo is changed so that the 


button is enabled if and only if an undo is possible. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 








Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 














As Long, ByVal _ 
Msg As Long, wParam As Any, lParam As Any) As Long 

Public Const EM_CANUNDO = &HC6 

Public Const EM UNDO = &HC7 




















' ***x Place the following code inside a form window. *** 


Private Sub Form_Load() 
' Make sure cmdUndo is initially disabled. 
cmdUndo.Enabled = False 

End Sub 














Private Sub txtBox_Change () 








' Whenever the contents of txtBox change, see if an undo is possible. 





























Dim possible As Long ' is it possible? 
possible = SendMessage(txtBox.hWnd, EM_CANUNDO, ByVal CLng(0), ByVal CLng(0)) 
' Since 0 = False and anything else = True, we can do this: 





cmdUndo.Enabled = possible 
End Sub 





Private Sub cmdUndo_Click () 














' Undo the last change the user made to the contents of txtBox. 


Dim retval As Long ' return value 

















retval = SendMessage(txtBox.hWnd, EM UNDO, ByVal CLng(0), 














ByVal CLng(0) ) 


' Since undo operations can themselves be undone, there's no 
' reason to send the EM_CANUNDO message here. cmdUndo is already enabled. 











End Sub 





Private Sub cmdSet_Click () 
' Set the contents of txtBox to a predetermined string. 
' using the Undo command or the EM_UNDO message. 











This can't be undone 


txtBox.Text = "You can't use Undo until you change this text!" 





End Sub 





See Also 


EM_UNDO 


Category 
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Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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EM_GETFIRSTVISIBLELINE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_GETFIRSTVISIBLELINE message to a multi-line edit control finds out which line is the first line visible. 
This is the line that is currently displayed at the top of the control. 


Return Value 


If the edit control is multi-line, the message returns the zero-based index of the first visible line at the top of the control. If the 
edit control is single-line, the message returns the zero-based index of the first visible character. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





























Const EM_GETFIRSTVISIBLELINE = &HCE 


Example 


Read the first visible line at the top of edit control Text1. Display the text on that line in the Debug window. This requires 
sending a series of edit control messages, if we do this via the API. To use this example, place a text edit control named Text] 
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and a command button named Command! on a form window. Make sure that the MultiLine property of Text1 is set to True 
before running the example. To get the first line of text, click button Command1. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 














As Any, Source _ 
As Any, ByVal Length As Long) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal _ 
Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM_GETFIRSTVISIBLELINE = &HCE 
Public Const EM GETLINE = &Hc4 
Public Const EM LINEINDEX = &HBB 
Public Const EM LINELENGTH = &HCl 



















































































' xxx Place the following code inside the form window. *** 


Private Sub Command1_Click () 















































Dim lineindex As Long ' index of the first visible line 

Dim charindex As Long ' index of the first character on that line 
Dim linetextlen As Integer ' length of that line (note the data type!) 
Dim linetext As String ' receives the line's text 

Dim retval As Long ' generic return value 




















' Get the zero-based index of Textl's first visible line. 

lineindex = SendMessage(Text1l.hWnd, EM_GETFIRSTVISIBLELINE, ByVal CLng(0), 
ByVal CLng(0) ) 

' Get the zero-based index of the first character on that line. This is 

" need for the message we'll send next. 

charindex = SendMessage(Textl.hWnd, EM LINETNDEX, ByVal lineindex, ByVal 



























































CLng (0) ) 





' Find out the number of characters on that line. Note how 
' we store this in a 16-bit value instead of the regular 32-bit Long. 
linetextlen = SendMessage(Textl.hWnd, EM LINELENGTH, ByVal charindex, ByVal 






































CLng (0) ) 








' Make enough room in the string to receive the text. However, 
' the string must be at least two bytes/characters long for what we'll do 








next. 








linetext = Space (IIf(linetextlen >= 2, linetextlen, 2)) 

' EM GETLINE wants the length of the string copied into the first 

" two bytes of the string passed to it. Unusual, but this is the simplest 
way around 

" the two-message-parameter limit. This is why linetextlen is only 16 bits 






































long. 








CopyMemory ByVal linetext, linetextlen, Len(linetextlen) 











' Finally, read the first line visible in Textl. 
retval = SendMessage(Textl.hWnd, EM GETLINE, ByVal lineindex, ByVal linetext) 
' In case we made the string too long (if the line was less than two 
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' characters long), shorten it back up. 








If linetextlen < 2 Then linetext = Left (linetext, linetextlen) 
' Finally, display the text. 
Debug.Print "The first line visible in Textl reads: "; linetext 








End Sub 


Category 
Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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EM _GETLINE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_GETLINE message to an edit control retrieves the contents of one of its lines. The copied text is placed into 
the string passed as /Param. 


Return Value 


If successful, the message returns the number of characters copied into the string passed as /Param. If an error occured (most 
likely if an invalid line was specified), the message returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the line to copy into the string passed as /Param. 

lParam 
A string that receives a copy of the contents of the specified line of the edit control. This string must already be long 
enough to receive the copied text. Also, before sending the message, the first two bytes of the string must contain a 16- 
bit integer specifying the length of the string. (See the example for a demonstration of how to do this.) 


Constant Definitions 





Const EM _GETLINE = &HC4 














Example 
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Read the first visible line at the top of edit control Text1. Display the text on that line in the Debug window. This requires 
sending a series of edit control messages, if we do this via the API. To use this example, place a text edit control named Text] 
and a command button named Command! on a form window. Make sure that the MultiLine property of Text] is set to True 
before running the example. To get the first line of text, click button Command1. 

















This code is licensed according to the tern 


Declarations and such needed for the example: 































































































ns and conditions listed here. 












































































































































































































































' (Copy them to the (declarations) section of a module.) 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal _ 
Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM GETFIRSTVISIBLELINE = &HCkE 
Public Const EM _GETLINE = &HC4 
Public Const EM LINEINDEX = &HBB 
Public Const EM LINELENGTH = &HC1 
' *** Place the following code inside the form window. *** 
Private Sub Command1_Click () 
Dim lineindex As Long ' index of the first visible line 
Dim charindex As Long ' index of the first character on that line 
Dim linetextlen As Integer ' length of that line (note the data type!) 
Dim linetext As String ' receives the line's text 
Dim retval As Long ' generic return value 
' Get the zero-based index of Textl's first visible line. 
lineindex = SendMessage(Textl.hWnd, EM GETFIRSTVISIBLELINE, ByVal CLng(0), 
ByVal CLng(0) ) 
' Get the zero-based index of the first character on that line. This is 
" need for the message we'll send next. 
charindex = SendMessage(Textl.hWnd, EM LINETINDEX, ByVal lineindex, ByVal 
CLng (0) ) 
' Find out the number of characters on that line. Note how 
' we store this in a 16-bit value instead of the regular 32-bit Long. 
linetextlen = SendMessage(Textl.hWnd, EM LINELENGTH, ByVal charindex, ByVal 
CLng (0) ) 
' Make enough room in the string to receive the text. However, 
' the string must be at least two bytes/characters long for what we'll do 
next. 
linetext = Space (IIf(linetextlen >= 2, linetextlen, 2)) 
' EM GETLINE wants the length of the string copied into the first 
" two bytes of the string passed to it. Unusual, but this is the simplest 


way around 


long. 


i 


the two-message-parameter limit. 








This is why linet 











CopyMemory ByVal linetext, linetextlen, 
' Finally, read the first line visible in Te 
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xtl. 


textlen is only 16 bits 





Len (linetextlen) 
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retval = SendMessage(Textl.hWnd, EM_GETLINE, ByVal lineindex, ByVal linetext) 


' In case we made the string too long (if the line was less than two 
' characters long), shorten it back up. 



































If linetextlen < 2 Then linetext = Left (linetext, linetextlen) 

' Finally, display the text. 

Debug.Print "The first line visible in Textl reads: "; linetext 
End Sub 


EM_LINELENGTH 


Category 
Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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EM _GETPASSWORDCHAR Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The EM_GETPASSWORDCHAR message identifies the password character used by an edit control. This characters appears 
in place of each character entered into the edit control, in order to hide its contents. As the name implies, this is typically done 
to hide a password entered into the control. 


Return Value 


The message returns the ASCII value of the password character used by the edit control. If the control does not use a password 
character, the message returns 0. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const EM_GETPASSWORDCHAR = &HD2 

















Example 


Identify the password character used by edit control Text! to hide its contents. To use this example, place a text edit box 
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named Textl and a command button named Command 1 on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" 











~ 


ByVal hWnd 











As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM GETPASSWORDCHAR = &HD2 





' *** Place the following code inside the form window. *** 


Private Sub Command1_Click () 
Dim passchar As Long ' ASCII code of the password character 




















passchar = SendMessage(Text1l.hWnd, EM_GETPASSWORDCHAR, ByVal CLng(0), ByVal 
































CLng (0) ) 
If passchar > 0 Then 
Debug.Print "The password character is "; Chr(passchar) 
Else 
Debug.Print "Textl does not use a password character." 
End If 
End Sub 





See Also 


EM_SETPASSWORDCHAR 


Category 


Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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EM GETSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The EM_GETSEL message identifies what text is currently selected in an edit control. The message effectively gives the 
character positions of the beginning and end of the selection. 


Return Value 


The message returns the start and end positions of the text selection, packed into a single 32-bit integer. The low-order word 
contains the starting position of the selection and the high-order word contains the position of the first character after the 
selection. However, it is easier to use the values placed into wParam and /Param to read the selection instead of using the 
return value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
Receives the zero-based position of the first character in the selection. 
lParam 
Receives the zero-based position of the character immediately after the end of the selection. 


Constant Definitions 




















Const EM_GETSEL = &HBO 


Example 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.d1ll1" Alias "SendMessageA" 








~ 


ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM_GETSEL = &HBO 














' Display the selected text in edit control Textl. This is done by sending messages 
" to get the selection, and then accessing the control's .Text property to read its 
contents. 




















Dim startpos As Long ' starting position of the selection 
Dim endpos As Long ' ending position of the selection 
Dim retval As Long ' return value 

Dim seltext As String ' the selected text 





' Figure out where the selection in Textl is. 
retval = SendMessage(Text1l.hWnd, EM_GETSEL, startpos, endpos) 












































' Now isolate that selection from th ntire text and display it. 
If startpos <> endpos Then 
seltext = Mid(Textl.Text, startpos + 1, endpos - startpos) 
Debug.Print "Text selection: "; seltext 
Else 
Debug.Print "No selection." 





End If 


See Also 


EM_REPLACESEL, EM_SETSEL 











Category 
Edit Controls 


Back to the Message list. 





Back to the Reference section. 
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EM_LINEINDEX Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_LINEINDEX< to an edit control gets the index of the first character on a line. This index is basically the 
number of characters between that character and the first character in the edit control. 


Return Value 


The message returns the zero-based index of the first character on the specified line of the edit control. The message returns -1 
if wParam refers to a line that does not exist. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the line. The message will return the index of this line's first character. A value of -1 for this 
parameter indicates the line that currently contains the caret. 

lParam 
Not used -- set to 0. 


Constant Definitions 








Const EM _LINEINDEX = &HBB 


























Example 
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Read the first visible line at the top of edit control Text1. Display the text on that line in the Debug window. This requires 
sending a series of edit control messages, if we do this via the API. To use this example, place a text edit control named Text] 
and a command button named Command! on a form window. Make sure that the MultiLine property of Text is set to True 
before running the example. To get the first line of text, click button Command1. 


F 


' 




















Declarations and such needed 





for the example: 











































































































This code is licensed according to the terms and conditions listed here. 











































































































































































































' (Copy them to the (declarations) section of a module.) 
Public Declare Sub CopyMemory Lib "kernel32.dll" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal Length As Long) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal _ 
Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM GETFIRSTVISIBLELINE = &HCkE 
Public Const EM GETLINE = &HC4 
Public Const EM_LINEINDEX = &HBB 
Public Const EM LINELENGTH = &HC1 
' ***x Place the following code inside the form window. *** 
Private Sub Command1_Click () 
Dim lineindex As Long ' index of the first visible line 
Dim charindex As Long ' index of the first character on that line 
Dim linetextlen As Integer ' length of that line (note the data type!) 
Dim linetext As String ' receives the line's text 
Dim retval As Long ' generic return value 
' Get the zero-based index of Textl's first visible line. 
lineindex = SendMessage(Textl.hWnd, EM GETFIRSTVISIBLELINE, ByVal CLng(0), 
ByVal CLng(0) ) 
' Get the zero-based index of the first character on that line. This is 
" need for the message we'll send next. 
charindex = SendMessage(Textl.hWnd, EM_LINEINDEX, ByVal lineindex, ByVal 
CLng (0) ) 
' Find out the number of characters on that line. Note how 
' we store this in a 16-bit value instead of the regular 32-bit Long. 
linetextlen = SendMessage(Textl.hWnd, EM LINELENGTH, ByVal charindex, ByVal 
CLng (0) ) 
' Make enough room in the string to receive the text. However, 
' the string must be at least two bytes/characters long for what we'll do 
next. 
linetext = Space (IIf(linetextlen >= 2, linetextlen, 2)) 
' EM GETLINE wants the length of the string copied into the first 






































why linetextlen 





this is the simplest 





is only 16 bits 


' two bytes of the string passed to it. Unusual, but 
way around 
' the two-message-parameter limit. This is 
long. 
CopyMemory ByVal linetext, linetextlen, Len(linetextlen) 
' Finally, read the first line visible in Textl. 
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retval = SendMessage(Textl.hWnd, EM GETLINE, ByVal lineindex, ByVal linetext) 


























' In case we made the string too long (if the line was less than two 
' characters long), shorten it back up. 

If linetextlen < 2 Then linetext = Left (linetext, linetextlen) 

' Finally, display the text. 

Debug.Print "The first line visible in Textl reads: "; linetext 











End Sub 





Category 
Edit Controls 


Back to the Message list. 





Back to the Reference section. 
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EM _LINELENGTH Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_LINELENGTH message to an edit control find out how many characters are on a particular line. This 
message find out the length of one of the control's lines, taking word wrapping into account. However, for some bizarre reason, 
the line is idenified by a character position and not a line index value. 


Return Value 


For multi-line edit controls, the message returns the number of characters on the specified line. For single-line edit controls, the 
message returns the total number of characters in the control. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of any character on the line to get the length of. Note that this is a character index, not a line 
index. (To get the index of the first character on a particular line, send the EM_LINEINDEX message before sending 
this message.) If this parameter is -1, the function returns the total number of unselected characters that are on lines that 
contain selected characters. 

lParam 
Not used -- set to 0. 


Constant Definitions 





Const EM _LINELENGTH = &HCl 
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Example 


Read the first visible line at the top of edit control Text1. Display the text on that line in the Debug window. This requires 
sending a series of edit control messages, if we do this via the API. To use this example, place a text edit control named Text] 
and a command button named Command! on a form window. Make sure that the MultiLine property of Text1 is set to True 
before running the example. To get the first line of text, click button Command1. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 

















As Any, Source _ 
As Any, ByVal Length As Long) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal _ 

Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM GETFIRSTVISIBLELINE = &HCE 
Public Const EM GETLINE = &Hc4 
Public Const EM LINEINDEX = &HBB 
Public Const EM_LINELENGTH = &HC1 







































































' *** Place the following code inside the form window. *** 








Private Sub Command1_Click () 













































































Dim lineindex As Long ' index of the first visible line 

Dim charindex As Long ' index of the first character on that line 
Dim linetextlen As Integer ' length of that line (note the data type!) 
Dim linetext As String ' receives the line's text 

Dim retval As Long ' generic return value 

' Get the zero-based index of Textl's first visible line. 

lineindex = SendMessage(Textl.hWnd, EM GETFIRSTVISIBLELINE, ByVal CLng(0), 









































ByVal CLng(0) ) 
' Get the zero-based index of the first character on that line. This is 
" need for the message we'll send next. 
charindex = SendMessage(Textl.hWnd, EM LINEITNDEX, ByVal lineindex, ByVal 





















































CLng (0) ) 





' Find out the number of characters on that line. Note how 

' we store this ina 16-bit value instead of the regular 32-bit Long. 

linetextlen = SendMessage(Textl.hWnd, EM_LINELENGTH, ByVal charindex, ByVal 
CLng (0) ) 

' Make enough room in the string to receive the text. However, 

' the string must be at least two bytes/characters long for what we'll do 



































next. 




















linetext = Space (IIf(linetextlen >= 2, linetextlen, 2)) 

' EM GETLINE wants the length of the string copied into the first 

" two bytes of the string passed to it. Unusual, but this is the simplest 
way around 

' the two-message-parameter limit. This is why linetextlen is only 16 bits 









































long. 
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CopyMemory ByVal linetext, linetextlen, Len(linetextlen) 
' Finally, read the first line visible in Textl. 
retval = SendMessage(Textl.hWnd, EM GETLINE, ByVal lineindex, ByVal linetext) 
' In case we made the string too long (if the line was less than two 

characters long), shorten it back up. 






































' 














If linetextlen < 2 Then linetext = Left (linetext, linetextlen) 
' Finally, display the text. 
Debug.Print "The first line visible in Textl reads: "; linetext 


End Sub 





See Also 


EM_GETLINE 








Category 
Edit Controls 


Back to the Message list. 
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EM REPLACESEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The EM_REPLACESEL message tells an edit control to replace the currently selected text with a different string. If nothing 
in the edit control is selected, then the text is instead inserted at the position of the caret. 


Return Value 


This message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
Specifies whether the text replacement should be added to the edit control's Undo list, which would allow the user to 
undo the operation. A nonzero value allows an undo; a value of 0 does not. 

lParam 
The text to replace the selection with. If nothing in the edit control is selected, this text is inserted at the current position 
of the caret. 


Constant Definitions 





Const EM _REPLACESEL = &HC2 

















Example 
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' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 






































Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 

Public Const EM_REPLACESEL = &HC2 

Public Const EM SETSEL = &HB1 

' Select the first five characters in edit control Textl. Then replace the newly 
































' selected text with the words "REPLACEMENT TEXT". 
Dim retval As Long ' return value 




















' First, select the first five characters of Textl. 

retval = SendMessage(Textl.hWnd, EM SETSEL, ByVal CLng(0), ByVal CLng(5)) 

' Then replace the selection with some other text. Allow the user to undo it. 
retval = SendMessage(Text1l.hWnd, EM_REPLACESEL, ByVal CLng(1), ByVal "REPLACEMENT 


TEXT") 













































































See Also 


EM_GETSEL, EM_SETSEL 


Category 
Edit Controls 


Back to the Message list. 
Back to the Reference section. 





Last Modified: May 21, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/e/em_replacesel.html 














http://216.26.168.92/vbapi/ref/e/em_replacesel.html (2 of 2) [9/1/2002 6:07:02 PM] 


Windows API Guide: EM_SETPASSWORDCHAR Message 
vbapi.com - part of the VB-World Network 


| WHITE | CLIFF 
| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





EM SETPASSWORDCHAR Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The EM_SETPASSWORDCHAR message sets the password character used by an edit control. This characters appears in 
place of each character entered into the edit control, in order to hide its contents. As the name implies, this is typically done to 
hide a password entered into the control. This message can also be used to tell an edit control not to use such a password 
character, instead telling it to actually display its contents. 


Return Value 


EM_SETPASSWORDCHAR does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The ASCII code of the character to use as the new password character. If this is 0, then the edit control will no longer 
use a password character. 

lParam 
Not used -- set to 0. 


Constant Definitions 





Const EM_SETPASSWORDCHAR = &HCC 














Example 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM_SETPASSWORDCHAR = &HCC 





' Have edit control Textl use a dash character to hide the password. 























Dim retval As Long ' meaningless return value 

retval = SendMessage(Text1l.hWnd, EM_SETPASSWORDCHAR, ByVal CLng(Asc("-")), ByVal 
CLng (0) ) 

See Also 


EM_GETPASSWORDCHAR 








Category 
Edit Controls 


Back to the Message list. 
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EM SETSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The EM_SETSEL message changes the current text selection inside an edit control. Once this message sets the selection, the 
edit control's caret is placed immediately at the end of the selection. 


Return Value 


This message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based position of the first character in the selection. If this is -1, no text is selected. 

lParam 
The zero-based position of the first character that appears immediately after the end of the selection. In other words, this 
is one plus the position of the last selected character. If this is -1, the selection extends to the end of the control. 


Constant Definitions 





Const EM_SETSEL = &HB1 

















Example 


' This code is licensed according to the terms and conditions listed here. 
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' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM REPLACESEL = &HC2 
Public Const EM_SETSEL = &HB1 





















































































































































' Select the first five characters in edit control Textl. Then replace the newly 
' selected text with the words "REPLACEMENT TEXT". 

Dim retval As Long ' return value 

' First, select the first five characters of Textl. 

retval = SendMessage(Text1l.hWnd, EM_SETSEL, ByVal CLlng(0), ByVal CLng(5) ) 

' Then replace the selection with some other text. Allow the user to undo it. 
retval = SendMessage(Textl.hWnd, EM REPLACESEL, ByVal CLng(1), ByVal "REPLACEMENT 








TEXT") 





See Also 


EM_GETSEL, EM_REPLACESEL 











Category 
Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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EM UNDO Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the EM_UNDO message to an edit control undoes the last change made to the control's text. Most changes to an edit 
control can be undone. However, programmatically setting the text (such as using WM_SETTEXT, for example) cannot be 


undone. On the other hand, though, undo operations themselves can be undone. The EM_UNDO message has the same effect 
as selecting "Undo" from the edit control's context menu. 


Return Value 


If the edit control is a single-line edit control, the message always returns a nonzero value. 


If the edit control is a multi-line edit control, the message returns a nonzero value if the undo was successful and zero if the 
undo failed. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 








Const EM _UNDO = &HC7 
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Example 


Demonstrate undo operations for an edit control. Place three controls on a form window: an edit control (text box) named 
txtBox, a command button named cmdUndo, and another command button named cmdSet. Pressing cmdSet sets the contents 
of txtBox to a predetermined string, a change that cannot be undone. Pressing cmdUndo, naturally, undoes the last change 
made by the user to txtBox. Whenever the contents of txtBox change, the enabled status of cmdUndo is changed so that the 


button is enabled if and only if an undo is possible. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 























' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.d1l1" Alias 
As Long, ByVal _ 

Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const EM CANUNDO = &HC6 
Public Const EM_UNDO = &HC7 





kkk 





' ***x Place the following code inside a form window. 
Sub Form_Load() 

' Make sure cmdUndo is 
cmdUndo.Enabled False 
End Sub 


Private 
initially disabled. 














Private Sub txtBox_Change () 
' Whenever the contents of txtBox change, 


Dim possible As Long ' is it possible? 









































"SendMessageA" ( 


ByVal hWnd 





see if an undo is possible. 


























possible = SendMessage (txtBox.hWnd, EM CANUNDO, ByVal CLng(0), ByVal CLng(0)) 
' Since 0 = False and anything else = True, we can do this: 
cmdUndo.Enabled = possible 
End Sub 
Private Sub cmdUndo_Click () 
" Undo the last change the user made to the contents of txtBox. 
Dim retval As Long ' return value 
retval = SendMessage(txtBox.hWnd, EM_UNDO, ByVal CLng(0), ByVal CLng(0) ) 




















' Since undo operations can themselves be undone, 
' reason to send the EM_CANUNDO message here. 











End Sub 





Sub cmdSet_Click () 

' Set the contents of txtBox to a predetermined string. 
' using the Undo command or the EM_UNDO message. 
txtBox.Text "You can't 
End Sub 


Private 

















See Also 


http://216.26.168.92/vbapi/ref/e/em_undo.html (2 of 3) [9/1/2002 6:07:14 PM] 





there's no 
cmdUndo is already 


nabled. 





This can't be undone 


use Undo until you change this text!" 
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EM_CANUNDO 








Category 


Edit Controls 


Back to the Message list. 
Back to the Reference section. 
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IPM _CLEARADDRESS Message 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_CLEARADDRESS message to an IP Address control clears its contents. 





Return Value 


The message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Not used -- set to zero. 


Constant Definitions 





Const IPM_CLEARADDRESS = &H464 














Example 


When the form loads, create an IP Address control and place it in the upper-left corner of the window. When the user clicks 
button cmdClear, the contents of the IP Address control are erased. 
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To use this example, create a command button named cmdClear and place it on a form window. The IP Address control will be 
created programmatically when the program starts. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type INITCOMMONCONTROLSEX TYPE 
dwSize As Long 
dwICC As Long 




















End Type 
Public Declare Function InitCommonControlskx Lib "comct132.d11" (lpInitCtrlis As _ 
INI TCOMMONCONTROLSEX TYPE) As Long 
ublic Const ICC_INTERNET_CLASSES = &H800 
ublic Declare Function CreateWindowEx Lib "user32.d1ll1" Alias "CreateWindowExA" 
ByVal dwExStyle As Long, 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 

hWndParent As Long, 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD &H40000000 
Public Const WS_VISIBLE = &H10000000 

Cc 

c 
































AG) 














tg 























~ 






























































Public Declare Function DestroyWindow Lib "user32.dll" (ByVal hWnd As Long) As Long 
tion SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM _CLEARADDRESS = ¢&H464 

















Public Declare Fun 














' xxx Place the following code inside the form window. *** 


Private hIPControl As Long ' handle to the IP Address control 





' When the form is initialized, create an IP Address control in the 

' upper-left corner of the form. 

Private Sub Form_Initialize() 

Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 























register 





Dim retval As Long ' generic return value 





' Register the IP Address control window class. 
With comctls 
.dwSize = Len(comctls) 
-dwICC = ICC_INTERNET_ CLASSE 

















3] 
wn 


End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 
0, 125, 20; 









































Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 
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End Sub 











' Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 











Dim retval As Long 


' return value 


retval = DestroyWindow (hIPControl) 





End Sub 





' Clear the contents of 


the 


' use clicks this button. 





Private Sub cmdClear_Click () 
Dim retval As Long 








IP Address control when the 


retval = SendMessage(hIPControl, IPM _CLEARADDRESS, 








CLng (0) ) 
End Sub 





See Also 


IPM_GETADDRESS, IPM_SETADDRESS 











Category 
IP Address Control 


Back to the Message list. 
Back to the Reference section. 








Last Modified: October 29, 2000 
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ByVal CLng(0), 





ByVal 
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IPM_GETADDRESS Message 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_GETADDRESS message to an IP Address control retrieves the address stored in it. The IP address is 


returned in host byte order, where the field 0 value (left-most component) is in the highest-order byte and the field 3 value 
(right-most component) is in the lowest-order byte. For an easy way to extract the components of the IP address, use the 
FIRST_IPADDRESS, SECOND_IPADDRESS, THIRD_IPADDRESS, and FOURTH_IPADDRESS macros. 























Return Value 


The message returns the number of blank fields in the IP Address control. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Receives the IP address stored in the control, in host byte order. If any of the fields in the control are blank, 0 is used to 
represent them. 


Constant Definitions 





Const IPM_GETADDRESS = &H466 




















Example 
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Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type WSADATA 
wVersion As Integer 
wHighVersion As Integer 
szDescription As String * 257 
szSystemStatus As String * 129 
iMaxSockets As Long 
iMaxUdpDg As Long 
lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dl1" (ByVal wVersionRequested As 
Integer, lpWSAData _ 
As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d1l" () As Long 
Public Type HOSTENT 
h_name As Long 









































h_aliases As Long 
h_addrtype As Integer 
h_length As Integer 
h_addr_list As Long 








End Type 
Public Const AF_INET = 2 
Public Declare Function htonl Lib "wsock32.dll" (ByVal hostlong As Long) As Long 
Public Declare Function gethostbyaddr Lib "wsock32.dll" (addr As Long, ByVal length 
As Long, ByVal _ 
protocol As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 
As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function lstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 
As Any, ByVal _ 
lpString2 As Any) As Long 
Public Type INITCOMMONCONTROLSEX TYPE 
dwSize As Long 
dwICC As Long 
End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INI TCOMMONCONTROLSEX TYPE) As Long 
Public Const ICC_INTERNET_CLASSES = &H800 
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Ae) 








ublic Declare Function CreateWindowEx Lib "user32.d1l1" Alias "CreateWindowExA" 
ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 

As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, _ 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.dll1" (ByVal hWnd As Long) As Long 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM ISBLANK = &H469 
Public Const IPM _GETADDRESS = &H466 














~ 














































































































' ***x Place the following code in a form window. *** 


Private hIPControl As Long ' handle to the IP Address control 


' When the form is initialized, create an IP Address control in the 
' upper-left corner of the form. 



































Private Sub Form_Initialize() 

Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 
register 

Dim retval As Long ' generic return value 











' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_ CLASSES 




















End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 
0, 125, 20, 



































Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





End Sub 








' Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














retval = DestroyWindow (hIPControl) 
End Sub 








F 


Look up the primary domain name of the host computer identified by the 
' address in the IP Address control. 

Private Sub cmdGetDomain_Click() 

Dim ipAddress_h As Long " the IP address, in host byte order 
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im 

















' Veri 


retval = SendMessage(hIPControl, 


ipAddress_n As Long i 











im sockinfo As WSADATA i 
Dim pHostinfo As Long : 
Dim hostinfo As HOSTENT ! 





domainName As String ' 
retval As Long i 


fy that an IP address 








If retval <> 0 Then 


End If 





' Get the IP address entered by the user and verii 


Debug.Print 
Exit Sub 











Y Tour 


the 





in 


pointer to 


IP address, 
formation about the Winsock 


information abou 














in 


the primary domain name of 
generic return val 


formation about the host 


ue 





was entered. 
IPM_ISBLANK, 











"No IP address was entered!" 





ntered. 





fields in the address 








retval = SendMessage(hIPControl, 








If retval < 4 Then 





End If 











Debug.Print "An inco 


Exit Sub 





wer 





mplete 


' Open up a Winsock v2.2 session. 


retval 


If retval <> 0 Then 





End If 











= WSAStartup(&H202, s 





Debug.Print " 
Exit Sub 





ockinfo) 


IPM_GETADDRESS, 





ERROR: Attempt to open Winsock failed: 


" Convert the IP address into network byte order. 


















































s_h) 


Address_n, 











4, AF_INET) 











the struc 
ByVal 














strlen(hos 
lstrcpy (domainName, 


in name int 








pHostinfo, 


Cure. 





to a string. 





name is: "; 


tinfo.h_name) ) 





hostinfo.h_name) 


domainName 


ipAddress_n = htonl(ipAddres 
' Get information about the host computer. 
pHostinfo = gethostbyaddr (ip 
If pHostInfo = 0 Then 
Debug.Print 
Else 
' Copy the data into 
CopyMemory hostinfo, 
" Copy the host doma 
domainName = Space (1 
retval = 
Debug.Print "Domain 
End If 
' End the Winsock session. 
retval = WSACleanup () 


End Sub 





See Also 


IPM_CLEARADDRESS, IPM_SETADDRESS 
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in network byte order 


implementation 








ByVal CLng (0), 


ByVal CLng (0), 


t the host computer 
computer 





the host computer 





ByVal CLng (0)) 


fy that all 


ipAddress_h) 


IP address was entered!" 


error"; retval 





"Could not find a host with the specified IP address." 


Len (hostinfo) 
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Category 
IP Address Control 


Back to the Message list. 
Back to the Reference section. 
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IPM_ISBLANK Function 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_ISBLANK message to an IP Address control determines whether the control is blank or not. An IP address 
control is considered blank if all four fields in it are empty. 





Return Value 


If the IP Address control is blank, the function returns a nonzero value. If the control is not entirely blank, the function returns 
zero. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Not used -- set to zero. 


Constant Definitions 





Const IPM_ISBLANK = &H469 








Example 


Create an IP Address control and use it to prompt the user for an IP address. When the user clicks button cmdGetDomain, the 
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program looks up the first domain name assigned to that address. 


To use this example, place a command button named cmdGetDomain on a form window. The IP Address control is created 
and destroyed by invoking API functions directly and does not need to be placed on the form beforehand. 





This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 


' (Copy them to the 
Public Type WSA 





End Type 
Public D 
Integer, 








Public D 
Public T 








End Type 


Public Const AF_INET 
Declare Functio 


Public 
Public 
As Long, 





D 





Public 
As Any, 


(declarations) section of a module.) 


DATA 





wVersion As Integer 
wHighVersion As Integer 





szDescript 
szsystemst 
iMaxSocket 











ion As String * 257 
atus As String * 129 
s As Long 


iMaxUdpDg As Long 
lpVendorInfo As Long 


eclare F 
lpWSADa 





eclare F 





unction WSAStartup Lib "wsock32.d1l1" ( 


ta 
As WSADATA) 


unction WSACleanup Lib "wsock32.d11" 








ByVal wVersionRequested As 


As Long 


() As Long 


ype HOSTENT 


h_name As 


Long 


h_aliases As Long 


h_addrtype 





As Integer 


h_length As Integer 


h_addr_lis 


Declare Function gethostbyaddr Lib "wsock32.d11" 





ByVal _ 


protocol As Long) 


eclare Sub 


Source _ 


t As Long 





2 
htonl Lib 


"wsock32.d11" (ByVal 





hostlong As Long) As Long 


ByVal length 














(addr As Long, 





As Long 
CopyMemory Lib "kernel32.d11" Alias 





"RtlMoveMemory" (Destination 





Public 
As Any) 
Public 


As Any, 


Declare F 


As Long 





Declare F 


ByVal lengt 
trlen Lib 


unction lsi 





th As Long) 








unc 


tion Jstrepy Lib 





"kernel32.d11" 


Alias 


"ls 


trlenA" ( 





"kernel32.d11" 








Alias 








S 


trcpyA" ( 





ByVal 


lpString 








ByVal 








lpStringl 





As Any, 











ByVal _ 


lpString2 As Any) 
Public Type INITCOMMONCONTROLSEX TYPI 


As Long 








(a 





dwSize As Long 
dwICC As Long 






































End Type 

Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INITCOMMONCONTROLSEX TYPE) As Long 

Public Const ICC_INTERNET CLASSES = &H800 


Public 








Declare Function CreateWindowEx Lib 





"user32.d1l1" Alias 





"CreateWindowExA" 
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~ 


ByVal dwExStyle As Long, 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, _ 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d1ll1" (ByVal hWnd As Long) As Long 



















































































Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 








As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 

Public Const IPM_ISBLANK = ¢&H469 

Public Const IPM GETADDRESS = &H466 


























' ***x Place the following code in a form window. *** 
Private hIPControl As Long ' handle to the IP Address control 


' When the form is initialized, create an IP Address control in the 

' upper-left corner of the form. 

Private Sub Form_Initialize() 

Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 























register 








Dim retval As Long ' generic return value 





' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_CLASSES 

















End With 
retval = InitCommonControlsEx(comctls) 














" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 


Oy 25, 20, 






































Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





End Sub 








' Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 








retval = DestroyWindow (hIPControl) 
End Sub 








' Look up the primary domain name of the host computer identified by the 
' address in the IP Address control. 

Private Sub cmdGetDomain_Click () 

Dim ipAddress_h As Long ' the IP address, in host byte order 
Dim ipAddress_n As Long ' the IP address, in network byte order 
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Verify that an IP address was entered. 





Dim sockinfo As WSADATA ' information about the Winsock implementation 
Dim pHostinfo As Long ' pointer to information about the host computer 
Dim hostinfo As HOSTENT ' information about the host computer 

Dim domainName As String ' the primary domain name of the host computer 
Dim retval As Long ' generic return value 


retval = SendMessage(hIPControl, IPM_ISBLANK, ByVal CLng(0), ByVal CLng(0) ) 
If retval <> 0 Then 





End If 











Debug.Print "No IP address was entered!" 
Exit Sub 











i 





Get the IP address entered by the user and verify that all 
four fields in the address wer ntered. 
























































Debug.Print "An incomplete IP address was entered!" 
Exit Sub 





End If 


Open up a Winsock v2.2 session. 


retval = WSAStartup(&H202, sockinfo) 


I 


G 








m 


ind If 


retval <> 0 Then 
Debug.Print "ERROR: Attempt to open Winsock failed: error"; 
Exit Sub 

















Convert the IP address into network byte order. 


ipAddress_n = htonl(ipAddress_h) 


' 


Get information about the host computer. 





pHostinfo = gethostbyaddr(ipAddress_n, 4, AF_INET) 
If pHostInfo = 0 Then 








re 


End Sub 














Else 





' Copy the data into the structure. 
CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) 











' Copy the host domain name into a string. 
domainName = Space(lstrilen(hostinfo.h_name) ) 














retval = lstrcpy(domainName, hostinfo.h_name) 








Debug.Print "Domain name is: "; domainName 


End If 


End the Winsock session. 
tval = WSACleanup () 





Category 


IP Address Control 
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retval = SendMessage(hIPControl, IPM GETADDRESS, ByVal CLng(0), ipAddress_h) 


If retval < 4 Then 


retval 


Debug.Print "Could not find a host with the specified IP address." 
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Back to the Message list. 
Back to the Reference section. 
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IPM_SETADDRESS Message 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_SETADDRESS message to an IP Address control sets the IP address stored in it. 





Return Value 


The message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


The IP address to put into the IP Address control. The IP address must be packed into a 32-bit integer and stored in host 
byte order. The MAKEIPADDRESS macro can be used to convert an IP address into this format. 





Constant Definitions 





Const IPM_SETADDRESS = &H465 














Example 


When the form window opens, create an IP address control in the upper-left corner and initialize it to the IP address of the 
computer. No special effort is needed to run this example, since the IP Address control is created programmatically when the 
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form loads. 





(Copy them to the 


Public Type WSADATA 





wVersion As Integer 
wHighVersion As Int 
Description As SI 








SZ! 


This code is licensed according to the tern 


Declarations and such needed for the exampl 
(declarations) 


Leger 
tring * 257 


section of 


ns and conditions 


e: 
a module.) 





szSystemStatus As String * 129 


iMaxSockets As Long 
































































































































listed here. 




















iMaxUdpDg As Long 

lpVendorInfo As Long 
End Type 
Public Declare Function WSAStartup Lib "wsock32.dll" (ByVal wVersionRequested As 
Integer, lpWSAData _ 

As WSADATA) As Long 
Public Declare Function WSACleanup Lib "wsock32.d1l1" () As Long 
Public Type HOSTENT 

h_name As Long 

h_aliases As Long 

h_addrtype As Integer 

h_length As Integer 

h_addr_list As Long 
End Type 
Public Const AF_INET = 2 
Public Declare Function gethostname Lib "wsock32.dll1" (ByVal name As String, ByVal 
namelen As Long) As Long 
Public Declare Function gethostbyname Lib "wsock32.dl11" (ByVal name As String) As 
Long 
Public Declare Function ntohl Lib "wsock32.d1ll" (ByVal hostlong As Long) As Long 
Public Declare Sub CopyMemory Lib "kernel32.d11" Alias "RtlMoveMemory" (Destination 
As Any, Source _ 

As Any, ByVal length As Long) 
Public Declare Function lstrlen Lib "kernel32.d11" Alias "lstrlenA" (ByVal lpString 
As Any) As Long 
Public Declare Function Ilstrcpy Lib "kernel32.d11" Alias "lstrcpyA" (ByVal lpStringl 
As Any, ByVal _ 





lpString2 As Any) 


As Long 





Public Type INITCOMMONCONTROLSI 





BAPE 








dwSize As Long 



























































dwICC As Long 
End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.dl11" 
INITCOMMONCONTROLSEX TYPE) As Long 
Public Const ICC_INTERNET CLASSES = &H800 
Public Declare Function CreateWindowEx Lib "user32.dll1" Alias "Crea 
(ByVal dwExStyle As Long, _ 











ByVal lpClassName As String, 





ByVal lpWindowName As String, 
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teWindowl!l 





(lpInitCtrls As _ 


EXA" 





ByVal dwStyle As 
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Long, ByVal x _ 
As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, _ 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d11l" (ByVal hWnd As Long) As Long 






























































Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 








As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM_SETADDRESS = &H465 





" Define a relevant API macro. 














Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val ("&H" & Right ("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 




















2)) 
End Function 








' *** Place the following code inside the form window. *** 


Private hIPControl As Long ' handle to the IP Address control 





' When the form is initialized, create an IP Address control in the 




































































' upper-left corner of the form. 
Private Sub Form_Initialize() 
Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 
register 
Dim sockinfo As WSADATA ' information about Winsock 
Dim hostinfo As HOSTENT ' information about an Internet host 
Dim pHostinfo As Long ' pointer to a HOSTENT structure 
Dim localhostName As String ' the computer's domain name 
Dim plPAddress As Long ' pointer to an IP address dword 
Dim ipAddress_n As Long ' the IP address in network byte order 
Dim ipAddress_h As Long ' the IP address in host byte order 
Dim retval As Long ' generic return value 

















' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_CLASSES 














End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 
0; T25; 207 



































Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





' Open a new Winsock session (version 2.2). 
retval = WSAStartup (MAKEWORD (2, 2), sockinfo) 
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If retval <> 0 Then 


Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval 
Exit Sub 








End If 














' Get the domain name of the computer, or, failing that, a string 

' that gethostbyname can handle to give an IP address. 

localhostName = Space (256) 

retval = gethostname(localhostName, 256) 

localhostName = Left (localhostName, InStr(localhostName, vbNullChar) - 1) 
' Get information about this computer on the network. 
' Get information about the domain specified in txtDomain. 
pHostinfo = gethostbyname (localhostName) 

































































If pHostinfo = 0 Then 
Debug.Print "Unable to resolve domain name." 











Else 








' Copy the data into a HOSTENT structure. 

CopyMemory hostinfo, ByVal pHostinfo, Len (hostinfo) 
If hostinfo.h_addrtype <> AF_INET Then 

Debug.Print "A non-IP address was returned." 




















Else 
1 


Copy the pointer to the first (and probably only) IP 








address in the structure. 
CopyMemory pIPAddress, ByVal hostinfo.h_addr_list, 4 
' Copy the actual IP address. 
CopyMemory ipAddress_n, ByVal pIPAddress, 4 














' Convert it to host byte order. 

ipAddress_h = ntohl (ipAddress_n) 

' Set the IP Address control to hold this address. 
retval = SendMessage(hIPControl, IPM_SETADDRESS, 
ByVal CLng(0), ByVal ipAddress_h) 























End If 














End Sub 





i 





Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 











retval = DestroyWindow (hIPControl) 
End Sub 








See Also 


IPM_CLEARADDRESS, IPM_GETADDRESS 


Category 


Winsock 
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Back to the Function list. 
Back to the Reference section. 
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IPM _SETFOCUS Message 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_SETFOCUS message to an IP Address contol gives the control the keyboard focus. The text in the 
particular field that is given the focus will automatically be selected. 





Return Value 


The message does not return a meaningful value. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
Specifies the (zero-based) field of the control to give the focus to. If this is greater than three, then the focus is set to the 
first blank field, or the first one if all fields are filled. 


Constant Definitions 


Const IPM_SETFOCUS = &H468 





Example 


When the form loads, create an IP Address control and place it in the upper-left corner of the window. When the user clicks 
button cmdClear, the contents of the IP Address control are erased and the keyboard focus is given to the first field in the 
control. 
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To use this example, create a command button named cmdClear and place it on a form window. The IP Address control will be 
created programmatically when the program starts. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type INITCOMMONCONTROLSEX TYPE 
dwSize As Long 
dwICC As Long 

















End Type 

Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INITCOMMONCONTROLSEX TYPE) As Long 

ublic Const ICC_INTERNET CLASSES = &H800 

ublic Declare Function CreateWindowEx Lib "user32.dll" Alias "CreateWindowExA" 
































tg 














tg 




















~ 


ByVal dwExStyle As Long, 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 

As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, _ 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.dll1" (ByVal hWnd As Long) As Long 

























































































Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 








As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM CLEARADDRESS = &H464 
Public Const IPM_SETFOCUS = &H468 


























' *** Place the following code inside the form window. *** 
Private hIPControl As Long ' handle to the IP Address control 


' When the form is initialized, create an IP Address control in the 

' upper-left corner of the form. 

Private Sub Form_Initialize() 

Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 




















register 





Dim retval As Long ' generic return value 





' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_CLASSES 




















End With 
retval = InitCommonControlsEx(comctls) 











" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 0, 
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0, 125, 20, 


Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





End Sub 








' Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 








retval = DestroyWindow (hIPControl) 
End Sub 








' Clear the contents of the IP Address control when the 
' use clicks this button. 

Private Sub cmdClear_Click () 

Dim retval As Long 





' Clear the contents of the control. 

retval = SendMessage(hIPControl, IPM CLEARADDRESS, ByVal CLng(0), ByVal 
CLng (0) ) 

' Give the first field (field 0) the keyboard focus. 

retval = SendMessage(hIPControl, IPM_SETFOCUS, ByVal CLng(0), ByVal CLng(0)) 
End Sub 
























































Category 


IP Address Control 





Back to the Message list. 
Back to the Reference section. 


Last Modified: October 29, 2000 
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IPM_SETRANGE Message 


Platforms 


Windows 95: Requires Internet Explorer 4.0 or later. 
Windows 98: Supported. 

Windows NT: Requires Internet Explorer 4.0 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the IPM_SETRANGE method to an IP Address control sets the valid input range. The range restricts which IP 


address are allowed to be entered in the control. If an out-of-range address is entered, the offending fields are adjusted to fall 
within range. (To clear the range, set the range of all four fields to 0-255, which is the range for all IP addresses.) 





Return Value 


If successful, the message returns a non-zero value. If an error occured, the message returns zero. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The (zero-based) field to set the range of. 

lParam 
A 16-bit integer that has the lower bound of the range in the low-order byte and the upper bound in the high-order byte. 
Use the MAKEIPRANGE macro to easily create this value. 


Constant Definitions 





Const IPM_SETRANGE = &H467 








Example 
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When the form loads, create an IP Address control and place it in the upper-left corner of the window. Restrict entries to the 
range 128.10.0.0 to 128.11.255.255. It is not necessary to prepare any controls for this example, since the IP Address control is 
created programmatically when the form loads. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Type INITCOMMONCONTROLSEX TYPE 
dwSize As Long 
dwICC As Long 














End Type 
Public Declare Function InitCommonControlsEx Lib "comct132.d1l1" (lpInitCtrls As _ 
INITCOMMONCONTROLSEX TYPE) As Long 
ublic Const ICC_INTERNET_CLASSES = &H800 
ublic Declare Function CreateWindowEx Lib "user32.d1l1" Alias "CreateWindowExA" 
ByVal dwExStyle As Long, _ 
ByVal lpClassName As String, ByVal lpWindowName As String, ByVal dwStyle As 
Long, ByVal x _ 

As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal 
hWndParent As Long, 
ByVal hMenu As Long, ByVal hInstance As Long, lpParam As Any) As Long 
Public Const WC_IPADDRESS = "SysIPAddress32" 
Public Const WS_CHILD = &H40000000 
Public Const WS_VISIBLE = &H10000000 
Public Declare Function DestroyWindow Lib "user32.d1l1" (ByVal hWnd As Long) As Long 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const IPM _SETRANGE = &H467 



































AG) 














tg 























~ 




























































































' Define a useful API macro. 

Public Function MAKEIPRANGE (ByVal low As Byte, ByVal high As Byte) As Long 
MAKEIPRANGE = low + CLng(high) * &H100 

End Function 












































' ***x Place the following code inside the form window. *** 
Private hIPControl As Long ' handle to the IP Address control 


' When the form is initialized, create an IP Address control in the 
© upper-left corner of the form. 






































Private Sub Form_Initialize() 

Dim comctls As INITCOMMONCONTROLSEX TYPE ' identifies the control to 
register 

Dim retval As Long ' generic return value 








' Register the IP Address control window class. 
With comctls 

.dwSize = Len(comctls) 

.dwICC = ICC_INTERNET_CLASSES 
End With 
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retval = InitCommonControlsEx(comctls) 





" Create the IP Address control in the corner of the window. 
hIPControl = CreateWindowEx (0, WC_IPADDRESS, "", WS_CHILD Or WS_VISIBLE, 
0 125, 20; 



































Me.hWnd, 0, App.hInstance, ByVal CLng(0)) 





" Restrict the range of valid IP address to 128.10.0.0 to 128.11.255.255. 
' (We only have to set the first two fields' range, since 0-255 is the 
default.) 
retval = SendMessage(hIPControl, IPM_SETRANGE, ByVal CLng(0), ByVal 


MAKEIPRANGE (128, 128)) 
retval = SendMessage(hIPControl, IPM_SETRANGE, ByVal CLng(1), ByVal 
MAKEIPRANGE (10, 11)) 

End Sub 







































































' Destroy the IP Address control when the form closes. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














retval = DestroyWindow (hIPControl) 
End Sub 





Category 


IP Address Control 





Back to the Message list. 
Back to the Reference section. 
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LB ADDSTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_ADDSTRING message to a list box control adds a string to its list. If the list box is sorted, the new string is 
added in its proper position according to the sort. If the list box is not sorted, the new string is added to the end. To control 
where the string is added, use the LB_INSERTSTRING message instead. 








Return Value 


If successful, the message returns the zero-based index of the newly added string's position in the list box. If there is 
insufficient space to store the new string, the message returns LB_ERRSTRING. If some other error occurs, the message 
returns LB_ERR. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


The string to add to the list box. 


Constant Definitions 








Const LB ADDSTRING = &H180 
Const LB_ERR = -1 
Const LB ERRSPACE = -2 
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Example 


When the user clicks button Command 1, empty the list box List1, and then add three strings to it. The order in which the 
strings appear will depend on whether the list box is sorted or not. 


To use this example, place a list box named Listl and a command button named Command! on a form window. To verify that 
the list box's list is being emptied, you may wish to add some items to it before running the example. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 


' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 
As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_ADDSTRING = &H180 
Public Const LB RESETCONTENT = &H184 















































' ***x Place the following code inside a form window. *** 





Private Sub Command1_Click () 
Dim retval As Long ' return value 








' Empty the list box Listl. 
retval = SendMessage(List1l.hWnd, LB RESETCONTENT, ByVal CLng (0), ByVal 



















































































CLng (0) ) 

' Now add three strings to List. Their exact placement will 

' depend on whether Listl is sorted or not. 

retval = SendMessage(List1l.hWnd, LB_ADDSTRING, ByVal CLng(0), ByVal "First 
Item Added") 

retval = SendMessage(Listl.hWnd, LB_ADDSTRING, ByVal CLng(0), ByVal "Second 
Item Added") 

retval = SendMessage(Listl.hWnd, LB_ADDSTRING, ByVal CLng(0), ByVal "Last 
Item Added") 
End Sub 





See Also 


LB_DELETESTRING, LB_INSERTSTRING, LB_-RESETCONTENT 














Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB DELETESTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_DELETESTRING message to a list box removes one of the items in it. 


Return Value 


If successful, the message returns the number of items remaining in the list box. If an error occured, the message returns 
LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the string to delete from the list box. 
lParam 

Not used -- set to zero. 


Constant Definitions 



































Const LB DELETESTRING = &H182 
Const LB_ERR = -1 
Example 


When the user clicks button Command 1, remove the second item from list box Listl. To run this example, place a list box 
named Listl and a command button named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 




















As Long, ByVal Msg _ 

As Long, wParam As Any, lParam As Any) As Long 
Public Const LB _DELETESTRING = &H182 
Public Const LB_ERR = -1 

















' *** Place the following code inside a form window. *** 


Private Sub Command1_Click () 
Dim result As Long ' result of string deletion attempt 














' Remove the second item from Listl and display the result. 
result = SendMessage(Listl.hWnd, LB_DELETESTRING, ByVal CLng(1), ByVal 
















































































CLng (0) ) 
If result = LB_ERR Then 
Debug.Print "Unable to delete the second string in List1l." 
Else 
Debug.Print "There are"; result; "strings left in Listl." 
End If 
End Sub 





See Also 


LB_ADDSTRING, LB_INSERTSTRING, LB_RESETCONTENT 

















Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB GETCOUNT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_GETCOUNT message determines how many items exist in a list box. Keep in mind that the list box items 
are zero-based; the first item has an index of zero, and the last one has an index of the count minus one. 


Return Value 


If successful, the message returns the number of items that are in the list box control. If an error occured, the message returns - 
1. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 

















Const LB GETCOUNT = &H18B 


Example 


Display the text of the second-to-last item in list box List! when the user clicks button Command 1. Obviously, to use this 
example you must place a list box named List1 and a command button named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" 





~ 


ByVal hWnd 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_GETCOUNT = &H18B 
Public Const LB GETTEXT = &H189 
Public Const LB GETTEXTLEN = &H18A 



































' xxx Place the following code inside a form window. *** 


Private Sub Command1_Click () 























Dim count As Long " number of items in the list box 
Dim s21 As Long ' index of the second-to-last item 
Dim itemtext As String ' text of that item 

Dim textlen As Long ' length of the item text 


' Figure out the index of the second-to-last item by subtracting two from 
' the total item count (remember, the index is zero-based). 
count = SendMessage(Listl.hWnd, LB_GETCOUNT, ByVal CLng(0), ByVal CLng(0)) 


s2l1 = count - 2 




















' Make the string long enough to receive that item's text. 

textlen = SendMessage(Listl.hWnd, LB GETTEXTLEN, ByVal s21, ByVal CLng(0)) 
itemtext = Space (textlen) & vbNullChar 
' Get the item text and remove the trailing null. 

textlen = SendMessage(Listl.hWnd, LB GETTEXT, ByVal s21, ByVal itemtext) 
itemtext = Left (itemtext, textlen) 

' Finally, display the result. 

Debug.Print "The second-to-last item is "; itemtext 
















































































End Sub 





Category 


List Boxes 


Back to the Message list. 





Back to the Reference section. 
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LB GETCURSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_GETCURSEL message to a single-selection list box gets the index of the selected item. To get the items 
selected in a multiple-selection list box, send the LB_GETSELITEMS message instead. 


Return Value 


If successful, the message returns the zero-based index of the selected item. If no item is selected, or if an error occured, the 
message returns LB_ERR. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Not used -- set to zero. 


Constant Definitions 





























Const LB _GETCURSEL = &H188 
Const LB_ERR = -1 
Example 


http://216.26.168.92/vbapi/ref/I/lb_getcursel.html (1 of 3) [9/1/2002 6:08:03 PM] 


Windows API Guide: LB_GETCURSEL Message 


Print the text of the selected item in single-selection list box List1. To use this example, place a list box named List! and a 


command button named Command! on a form window. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 








This code is licensed according to the terms and conditions listed here. 


Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 





As Long, _ 
ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB _GETCURSEL = &H188 

Public Const LB GETTEXT = &H189 

Public Const LB GETTEXTLEN = &H18A 


Public Const LB_ERR = -1 


















































' xxx Place the following code inside the form window. *** 





Private Sub Command1_Click () 

















Dim selitem As Long ' index of the selected item 
Dim textlen As Long ' length of the item's text 
Dim itemtext As String ' text of the selected item 








' Get the index of the selected item. 

selitem = SendMessage(List1l.hWnd, LB_GETCURSEL, ByVal CLng (0), 
If selitem = LB ERR Then 
Debug.Print "No item is selected." 









































Else 








' Get the text of the selected item. 
textlen = SendMessage(Listl.hWnd, LB GETTEXTLEN, ByVal 
































ByVal CLng(0)) 




















CLng(0)) + 1 















































selitem, ByVal 





itemtext = Space (textlen) 
textlen = SendMessage(Listl.hWnd, LB GETTEXT, ByVal selitem, ByVal 
itemtext) 
' Print the result. 
Debug.Print "Selected item: "; Left (itemtext, textlen) 
End If 
End Sub 





See Also 


LB_GETSELITEMS, LB_SETCURSEL 








Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB GETSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_GETSEL message to a list box checks to see if a particular item is selected. 


Return Value 


If the item is selected, the message returns a value greater than zero. If the item is not selected, the message returns zero. If an 
error occured, the message returns LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the item to check the selection state of. 
lParam 

Not used -- set to zero. 


Constant Definitions 





























Const LB GETSEL = &H187 
Const LB ERR = -1 
Example 


Check to see if the third item of list box List1 is selected. To use this example, place a list box named List] and a command 
button named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 











As Long, 





ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_GETSEL = &H187 





' ***x Place the following code inside the form window. *** 





Private Sub Command1_Click () 
Dim sel As Long ' selection state of the item 














' Check the selection state of Listl's third item. 
sel = SendMessage(List1l.hWnd, LB_GETSEL, ByVal CLng(2), ByVal CLng(0)) 






































If sel > 0 Then 

Debug.Print "The third item is selected." 
ElseIf sel = 0 Then 

Debug.Print "The third item is not selected." 
Else 

Debug.Print "An error occured!" 
End If 





End Sub 





See Also 


LB_GETCURSEL, LB_GETSELITEMS, LB_SETSEL 











Category 


List Boxes 


Back to the Message list. 





Back to the Reference section. 
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LB GETSELCOUNT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_GETSELCOUNT message to a multiple-selection message box counts the number of items that are selected. 


Return Value 


If successful, the message returns the number of items that are selected in the list box. If an error occured, the message returns 
LB_ERR. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Not used -- set to zero. 


Constant Definitions 





























Const LB_GETSELCOUNT = &H190 
Const LB_ERR = -1 
Example 


Display a list of all items that are selected in a list box. To use this example, place a multi-select list box named List1 and a 
command button named Command! on a form window. 
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' This code is licensed according to the tern 


' Declarations and such needed 





' (Copy them to the 
Public 
As Long, 








Public Const 


(declarations) 
Declare Function SendMessage Lib 





for the example: 





£ 


section of a module.) 


"user32.d1l1" Alias 








ByVal Msg As Long, 
LB_GETSELCOUNT = & 


wParam As Any, 

















Public Const LB GETSELIT 





190 








EMS = & 








' **x* Place 





Private Sub 
Dim 
Dim 
Dim 
Dim 


items () 


c As Long 








" Count the number oi 


the following code 


Command1_Click () 
As Long ' 
numsel As Long f 


retval As Long ' 









































191 





inside the 


form window. 


lParam As Any) 


ns and conditions listed here. 





As Long 


KK* 





indexes of the select 





ed items 





number of selected ił 
counter variable 
return value 


f selected items. 
= SendMessage(Listl.hWnd, LB _GETSELCOUNT, 





ms 





























numsel ByVal CLhLng(0), ByVal 
CLng (0) ) 
If numsel = 0 Then 
Debug.Print "No items are selected." 
Else 
' Resize the array so it can hold all the indexes. 
ReDim items (0 To numsel - 1) As Long 
' Get the indexes of all selected items. 
retval = SendMessage (List1.hWnd, LB GETSELITEMS, ByVal numsel, 
items (0) ) 
' Display them. 
Debug.Print "The following items are selected (identified by index): 
For c 0 To numsel - 1 
Debug.Print items (c); 
Next c 
Debug.Print 
End If 
End Sub 





See Also 


LB_GETSELITEMS 


Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 





















































http://216.26.168.92/vbapi/ref/l/lb_getselcount.html (2 of 3) [9/1/2002 6:08:16 PM] 


"SendMessageA" (ByVal hWnd 


Windows API Guide: LB_GETSELCOUNT Message 


Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@vbapi.com Send Encrypted E-Mail 








This page is at http://www.vbapi.com/ref/I/lb_getselcount.html 





http://216.26.168.92/vbapi/ref/I/lb_getselcount.html (3 of 3) [9/1/2002 6:08:16 PM] 


Windows API Guide: LB_GETSELITEMS Message 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





LB GETSELITEMS Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_GETSELITEMS message to a multiple-selection list box retrieves an list of all the selected items. The index 
of each selected item is copied into an array passed with the message. For single-selection list boxes, send the 
LB_GETCURSEL message instead. 








Return Value 


If successful, the message returns the number of item indexes copied into the array. If an error occured, the function returns 
LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The number of list box item indexes that the array passed as /Param can hold. 

lParam 
The array that receives the indexes of the selected items. If the array is too small, then only some of the indexes are 
copied over. To get the minimum length needed for all the indexes, use the LB_GETSELCOUNT message. 








Constant Definitions 





Ea 
Ud 
Q 


_GETSELITEMS = &H191 
LB_ERR = -1 








Const 
Const 

















CT CF 








Example 
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Display a list of all items that are selected in a list box. To use this example, place a multi-select list box named List1 and a 
command button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 
As Long, 














ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB GETSELCOUNT = &H190 


Public Const LB_GETSELITEMS = &H191 















































' *** Place the following code inside the form window. *** 





Private Sub Command1_Click () 

















Dim items() As Long ' indexes of the selected items 
Dim numsel As Long " number of selected items 

Dim c As Long ' counter variable 

Dim retval As Long ' return value 














' Count the number of selected items. 
numsel = SendMessage(Listl.hWnd, LB GETSELCOUNT, ByVal CLng(0), ByVal 




























































































CLng (0) ) 
If numsel = 0 Then 
Debug.Print "No items are selected." 
Else 
' Resize the array so it can hold all the indexes. 
ReDim items(0 To numsel - 1) As Long 
' Get the indexes of all selected items. 
retval = SendMessage(List1l.hWnd, LB_GETSELITEMS, ByVal numsel, 
items (0) ) 
' Display them. 
Debug.Print "The following items are selected (identified by index) :" 
For c = 0 To numsel - 1 
Debug.Print items(c); 
Next c 
Debug.Print 
End If 
End Sub 





See Also 


LB_GETCURSEL, LB_GETSEL, LB_GETSELCOUNT 


Category 


List Boxes 
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LB GETTEXT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The LB_GETTEXT message retrieves the text of one of the items in a list box control. 


Return Value 


If successful, the message returns the length of the string copied into the string passed as /Param, not including the terminating 
null character. If an error occured, the message returns -1. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the list box item to retrieve the text of. (The first item has an index of 0, etc.) 

lParam 
The string to copy the list box item text into. The string must have enough room to receive the entire string along with a 
terminating null character. 


Constant Definitions 

















Const LB _GETTEXT = &H189 


Example 


Display the text of the second-to-last item in list box List! when the user clicks button Command 1. Obviously, to use this 
example you must place a list box named List] and a command button named Command! on a form window. 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" 








As Long, ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB GETCOUNT = &H18B 
Public Const LB _GETTEXT = &H189 
Public Const LB GETTEXTLEN = &H18A 






































' xxx Place the following code inside a form window. *** 


Private Sub Command1_Click () 























Dim count As Long " number of items in the list box 
Dim s21 As Long ' index of the second-to-last item 
Dim itemtext As String ' text of that item 

Dim textlen As Long ' length of the item text 


~ 





ByVal hWnd 


' Figure out the index of the second-to-last item by subtracting two from 





' the total item count (remember, the index is zero-based). 

















count = SendMessage(Listl.hWnd, LB GETCOUNT, ByVal CLng(0), ByVal CLng(0)) 

















s2l1 = count - 2 


' Make the string long enough to receive that item's text. 
textlen = SendMessage(Listl.hWnd, LB GETTEXTLEN, ByVal s21, ByVal 




















CLng (0) ) 














itemtext = Space (textlen) & vbNullChar 
' Get the item text and remove the trailing null. 























textlen = SendMessage(Listl.hWnd, LB_GETTEXT, ByVal s21, ByVal itemtext) 











itemtext = Left (itemtext, textlen) 
' Finally, display the result. 
Debug.Print "The second-to-last item is "; itemtext 








End Sub 





See Also 


LB_GETTEXTLEN 


Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB GETTEXTLEN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The LB_GETTEXTLEN message retrieves the length of the text of one of the items in a list box control. The reported length 
does not include its terminating null character. When determining how long to size a string to receive the list box item's text, 
remember to add one to include the null. 


Return Value 


If successful, the message returns the length of the list box item's text, not including the terminating null character. If an error 
occured, the message returns -1. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the list box item to retrieve the length of the text of. (The first item has an index of 0, etc.) 
lParam 

Not used -- set to 0. 


Constant Definitions 





Const LB _GETTEXTLEN = &H18A 

















Example 


Display the text of the second-to-last item in list box List! when the user clicks button Command 1. Obviously, to use this 
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example you must place a list box named List] and a command button named Command! on a form window. 


i 








Public Declare Function SendMessage Lib 


Declarations and such needed for the example: 
' (Copy them to the (declarations) 


section of a module.) 





As Long, ByVal Msg As Long, 


Public Const LB GETCOUNT = &H18B 
Public Const LB GETTEXT = &H189 


























Public Const LB_GETTEXTLEN = &H18A 


wParam As Any, 


"user32.dl11" Alias 


"SendMessageA" 


lParam As Any) 


' xxx Place the following code inside a form window. *** 





Private Sub Command1_Click () 

Dim count As Long ' 
Dim s2l1 As Long ' 
Dim itemtext As String ' 
Dim textlen As Long i 




















Figure out the index of 





' the total item count (remember, 





count = SendMessage(Listl. 








s2l1 = count - 2 


number of items in the list box 
second-to-last item 
item 


index of the 
text of that 











length of the item text 








This code is licensed according to the terms and conditions listed here. 


~ 


ByVal hWnd 





As Long 





the second-to-last item by subtracting two from 








hWnd, LB GETCOUNT, 














the index is zero-based). 
ByVal CLng(0), ByVal CLng(0)) 








' Make the string long enough to receive that item's text. 





textlen = SendMessage (List1.hWnd, LB_GETTEXTLEN, 











itemtext = Space (textlen) 








& vbNullChar 





' Get the item text and remove the trailing null. 





textlen = SendMessage(Listl.hWnd, LB G EXT, ByVal 




















Bd 











ByVal s21, ByVal CLng(0) ) 





s2l, 





ByVal itemtext) 











itemtext Left (itemtext, 


textlen) 


' Finally, display the result. 





End Sub 





See Also 


LB_GETTEXT 





Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB_INSERTSTRING Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_INSERTSTRING message to a list box inserts a string into it. The string is placed at the position specified in 
the parameters, regardless of whether the list box is sorted or not. 


Return Value 


If successful, the message returns the zero-based index of the newly added string's position in the list box. If there is 
insufficient space to store the new string, the message returns LB_ERRSTRING. If some other error occurs, the message 
returns LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The zero-based index of the position to insert the string in the list box. If this is -1, the string is added to the end of the 
list. 

lParam 
The string to add to the list box. 


Constant Definitions 























Const LB _INSERTSTRING = &H181 
Const LB_ERR = -1 
Const L ~RRSPACE = -2 























http://216.26.168.92/vbapi/ref/I/lb_insertstring.html (1 of 3) [9/1/2002 6:08:35 PM] 


Windows API Guide: LB_INSERTSTRING Message 


Example 


When the user clicks button Command 1, insert three strings into list box List1. One string is added to the beginning, one to the 
third position, and one to the end. To run this example, place a list box named List1 and a command button named Command 1 


on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 








Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" 








As Long, ByVal Msg _ 
As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_INSERTSTRING = &H181 





' ***x Place the following code inside a form window. *** 





Private Sub Command1l_Click () 
Dim retval As Long ' return value 








' Add a string to the beginning of the drop-down box. 
retval = SendMessage(Listl.hWnd, LB_INSERTSTRING, ByVal CLng(0), 


























(ByVal hWnd 





ByVal "First 


























Item") 

' Insert a string at the third position in the drop-down box. 

retval = SendMessage(Listl.hWnd, LB_INSERTSTRING, ByVal CLng(2), ByVal "Third 
Item") 

' Add a string to the end of the drop-down box. 

retval = SendMessage(Listl.hWnd, LB_INSERTSTRING, ByVal CLng(-1), ByVal "Last 
Item") 
End Sub 





See Also 


LB_ADDSTRING, LB_DELETESTRING, LB_RESETCONTENT 


Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 





Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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LB RESETCONTENT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_LRESETCONTENT message to a list box removes all items from it. 


Return Value 


This message always returns zero. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 





Const LB RESETCONTENT = &H184 

















Example 


When the user clicks button Command 1, empty the list box List1, and then add three strings to it. The order in which the 
strings appear will depend on whether the list box is sorted or not. 
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To use this example, place a list box named List! and a command button named Command! on a form window. To verify that 
the list box's list is being emptied, you may wish to add some items to it before running the example. 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 
' (Copy them to the 


Public 
As Long, 





Public Const 
' *** Place the 


Private Sub Commandl 
Dim retval As Long ' 





i 











LB AD 











(declarations) 
Declare Function SendMessage Lib 
ByVal Msg _ 

As Long, 
Public Const 


wParam As Any, 
DSTRING 





&H180 











foll 


LB_RESETCONTENT 


owing code inside a form window. 











_Click () 


Empty the list box Listl. 
l.hWnd, LB_RESETCONTENT, 
































&H184 


return value 





section of 
"user32.dl11" 





lParam As Any) 


a module.) 


As Long 





























Alias 


KkK* 





"SendMessageA" ( 




















ns and conditions listed here. 





ByVal hWnd 

















retval = SendMessage (List ByVal CLng (0), ByVal 
CLng (0) ) 

' Now add three strings to List. Their exact placement will 

' depend on whether Listl is sorted or not. 

retval = SendMessage(Listl.hWnd, LB ADDSTRING, ByVal CLng(0), ByVal "First 
Item Added") 

retval = SendMessage(Listl.hWnd, LB ADDSTRING, ByVal CLng(0), ByVal "Second 
Item Added") 

retval = SendMessage(Listl.hWnd, LB ADDSTRING, ByVal CLng(0), ByVal "Last 
Item Added") 
End Sub 





See Also 


LB_ADDSTRING, LB_DELETESTRING, LB_INSERTSTRING 




















Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB SETCURSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_LSETCURSEL message to a single-selection list box sets the item that is currently selected, or clears the 
selection entirely. For multiple-selection list boxes, send the LB_SETSEL message instead. 


Return Value 


If successful, the message returns 1. If an error occured, or if the selection was cleared, the message returns LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

The zero-based index of the item to select. To clear the selection, set this to -1. 
lParam 

Not used -- set to zero. 


Constant Definitions 





























Const LB _SETCURSEL = &H186 
Const LB_ERR = -1 
Example 


Select the second item in list box Listl. To use this example, place a single-selection list box named List! and a command 
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button named Command! on a form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 














As Long, _ 


ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_SETCURSEL = &H186 








' xxx Place the following code inside the form window. *** 








Private Sub Command1_Click () 
Dim retval As Long ' return value 





' Change the selection in list box List1l to the second item. 
retval = SendMessage(Listl.hWnd, LB_SETCURSEL, ByVal CLng(1), ByVal CLng(0)) 


End Sub 

















See Also 


LBE_GETCURSEL, LB SETSEL 


Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 
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LB SETSEL Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the LB_SETSEL to a multiple-selection list box selects or deselects one of its items. Alternatively, the message can 
select or deselect all of the items simultaneously. For a single-selection list box, sned the LB_SETCURSEL message instead. 


Return Value 


If successful, the message returns zero. If an error occured, the message returns LB_ERR. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
If this is zero, the item is deselected. If this is a non-zero value, the item is selected. 
lParam 
The zero-based index of the item to select or deselect. If this is -1, all items in the list box are selected or deselected. 


Constant Definitions 





ETSEL = &H185 





Const 
Const 








ES 
wW W 
(6p) 











CT ce 








Example 


Change the selection in list box List1 so that the only selected items are the first and third items. To use this example, place a 
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multiple-selection list box named List1 and a command button named Command 1 on a form window. 


' This code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dll1" Alias "SendMessageA" (ByVal hWnd 

















As Long, _ 


ByVal Msg As Long, wParam As Any, lParam As Any) As Long 
Public Const LB_SETSEL = &H185 











' ***x Place the following code inside the form window. *** 





Private Sub Command1_Click () 
Dim retval As Long ' return value 








' First, deselect all items in the list box. 
retval = SendMessage(Listl.hWnd, LB_SETSEL, ByVal CLng (0), ByVal CLng(-1)) 


' Then, select the first and third items. 
retval = SendMessage(Listl.hWnd, LB_SETSEL, ByVal CLng (1 
retval = SendMessage(Listl.hWnd, LB_SETSEL, ByVal CLng (l 


End Sub 




















~~ 
` 


ByVal CLng(0)) 
ByVal CLng(2)) 























mt 
` 














See Also 


LB_GETSEL, LB_SETCURSEL 


Category 


List Boxes 


Back to the Message list. 
Back to the Reference section. 





Last Modified: January 21, 2001 
This page is copyright © 2001 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 


E-mail: vbapi@vbapi.com Send Encrypted E-Mail 
This page is at http://www.vbapi.com/ref/I/lb_setsel.html 














http://216.26.168.92/vbapi/ref/I/lb_setsel.html (2 of 2) [9/1/2002 6:08:50 PM] 


Windows API Guide: MM_MCINOTIFY Message 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





MM_MCINOTIFY Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


A window receives the MM_MCINOTIFY message in response to the completion of a MCI device's action when the "notify 
option is used. This tells the window that the MCI command has finished, whether because of success, failure, or some other 
event. The MM_MCINOTIFY message is only sent when the "notify" option was originally specified. 


Return Value 


The MM_MCINOTIFY message should return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
One of the following flags specifying the result of the original MCI command: 
MCI NOTIFY_ABORTED 
The MCI device aborted execution of the command. 
MCI NOTIFY_FAILURE 
An error occured while executing the command. 
MCI NOTIFY_SUCCESSFUL 
The MCI device successfully executed the command. 
MCI NOTIFY_SUPERSEDED 
Another command for the MCI device requested notification, so the window will not receive any notification 
when the command actually finishes. 
lParam 
The identifier of the MCI device that sent thge message. 


http://216.26.168.92/vbapi/ref/m/mm_mcinotify.html (1 of 4) [9/1/2002 6:08:55 PM] 


Windows API Guide: MM_MCINOTIFY Message 


Constant Definitions 





















































Const MM MCINOTIFY = &H3B9 

Const MCI_NOTIFY_ABORTED = &H4 
Const MCI_NOTIFY_FAILURE = &H8 
Const MCI_NOTIFY_SUCCESSFUL = &H1 
Const MCI_NOTIFY_SUPERSEDED = &H2 






































Example 


' 


' 














This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 


















































































































































' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 
lpstrCommand As String, ByVal lpstrReturnString As String, ByVal 
uReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 
Public Const MM MCINOTIFY = &H3B9 
Public Const MCI_NOTIFY_ ABORTED = &H4 
Public Const MCI_NOTIFY_FAILURE = &H8 
Public Const MCI_NOTIFY_SUCCESSFUL = &H1 
Public Const MCI_NOTIFY_ SUPERSEDED = &H2 
Public Declare Function CallWindowProc Lib "user32.dl11" Alias "CallWindowProcA" 
(ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam As 
Long, _ 
ByVal lParam As Long) As Long 
Public Declare Function SetWindowLong Lib "user32.dll" Alias "SetWindowLongA" (ByVal 
hWnd _ 
As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 
Public Const GWL_WNDPROC = (-4) 
' When the user pushes button Commandl, begin playing a MIDI file. Do not wait 
' for the music to finish, but display a simple message prompt when the end of 
' the MIDI file has been reached. Do this by using the "notify" option of the "play" 
' MCI command. Make sure the device is closed before quitting. 
' *** Place the following code inside a module. *** 





' 





Public pOldProc As Long 


' Custom window procedure for Forml. 











Public Function WindowProc (ByVal hWnd 
Long, _ 
ByVal lParam As Long) 
Dim mbtext As String ' text o 
Dim retval As Long ' return 








If the notification message 





























Pointer to window Forml's previous window procedure. 











As Long, ByVal uMsg As Long, ByVal wParam As 
As Long 

f message box 

value 


is received, tell the user how 
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' the playback of the MIDI file concluded. 


Select Case uMsg 
Case MM MCINOTIFY 
Select Case wParam 
Case MCI_NOTIFY_ABORTED 
mbtext = "Playback of the 
Case MCI_NOTIFY_FATLURE 


























Case MCI_NOTIFY_SUCCESSFUL 
mbtext = "Playback of the 
N 


OTIFY_SUPERSEDED 















































Case MCI 























device." 
End Select 








retval = MsgBox (mbtext, vbOkOnly Or vbIni 


WindowProc = 0 
Case Else 
retval = CallWindowProc(pOldProc, 

















End Select 
End Function 





' *** Place the following code inside Forml. *** 





Private Sub Command1_Click () 








' Open and start playing a MIDI file. Have the devic 


' playback has ended. 

















MIDI file was somehow aborted." 




















mbtext = "An error occured while playing the MIDI file." 
N 





MIDI file concluded successfully." 





Formation) 


mbtext = "Another command requested notification from this 


hWnd, uMsg, wParam, lParam) 





notify Forml once 


Dim retval As Long ' return value 
retval = mciSendString ("open C:\Music\song.mid alias music", "", 0, 0) 
retval = mciSendString("play music notify", "", 0, Forml.hWnd) 


End Sub 





Private Sub Forml_Load() 


' Set up the custom window procedure for use with Forml. 


pOldProc = SetWindowLong(Forml.hWnd, GWL_WN 





End Sub 





Private Sub Forml_Unload(Cancel As Integer) 
Dim retval As Long ' return value 





' Make sure that the MIDI file is closed. 
retval = mciSendString("close music", "", 














0, 0) 


' Restore Forml's original window procedure. 





retval = SetWindowLong(Forml.hWnd, GWL_WN 
End Sub 








Category 


Media Control Interface (MCI) 





Back to the Function list. 
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DPROC, pOldProc) 





DPROC, AddressOt 


f WindowProc) 
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Back to the Reference section. 
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WM_COMMAND Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


A window receives the WM_COMMAND message when the user selects an item in one of the window's menus. This 
includes any popup menus which the window owns. Upon receiving this message, the window should perform whatever task 
or operation the menu item was meant to perform. 


Return Value 


The WM_COMMAND message should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The high-order word is the notification code of the message: 0 means the message was generated by selecting a menu 
item, whereas 1 means the message was generated by a keyboard accelerator. The low-order word contains the 
identifier of the menu item that the user selected. The LOWORD and HIWORD macros can extract these two values. 
lParam 
A handle to the control that sent this message, if any. If no control sent the message, this is 0. 


Constant Definitions 


Const WM_COMMAND = &H111 





Example 
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Y Thys 





code is licensed according to the terms and conditions listed here. 


' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 


Public 
Public 
Public 















































Type MENUITEMINFO 
cbhSize As Long 

fMask As Long 

fType As Long 

fState As Long 

wID As Long 

hSubMenu As Long 

hbmpChecked As Long 

hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 
cch As Long 






















































































Declare Function CreatePopupMenu Lib "user32.dl1l1" () 
Declare Function DestroyMenu Lib "user32.dll1" (ByVal hMenu As Long) 


As Long 



































As Long 


End Type 

Public Const MIIM_STATE = &H1 

Public Const MIIM_ID = &H2 

Public Const MIIM_TYPE = &H10 

Public Const MFT_SEPARATOR = &H800 

Public Const MFT STRING = &HO 

Public Const MFS_ DEFAULT = &H1000 

Public Const MFS ENABLED = &HO 

Public Declare Function InsertMenuItem Lib "user32.dl1" Alias "InsertMenulItemA" 

(ByVal _ 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As _ 
MENUITEMINFO) As Long 

Public Type RECT 





Public 





Public 


As _ 

Public 
Public 
Public 
Public 








left As Long 
top As Long 
right As Long 
bottom As Long 


End Type 





Type TPMPARAMS 


cbhSize As Long 
rcExclude As RECT 








End Type 








Declare Function TrackPopupMenuEx Lib "user32.dl1l1" 











fuFlags As Long, ByVal x As Long, ByVal y As Long, 





TPMPARAMS) As Long 























Const TPM _LEFTALIGN = &HO 
Const TPM_TOPALIGN = &HO 
Const TPM_LEFTBUTTON = &HO 





Type POINT TYPE 
x As Long 
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(ByVal hMenu As Long, 





ByVal hWnd As Long, 





ByVal 


lptpm 
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y As Long 
End Type 
Public Declare Function GetCursorPos Lib "user32.d11" (lpPoint As POINT TYPE) As Long 
Public Declare Function SetRectEmpty Lib "user32.d11" (lpRect As RECT) As Long 
Public Declare Function SetWindowLong Lib "user32.dll1" Alias "SetWindowLongA" (ByVal 
hWnd _ 
As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 
Public Const GWL_WNDPROC = -4 
Public Declare Function CallWindowProc Lib "user32.d1ll" Alias "CallWindowProcA" 
(ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 
Public Const WM_COMMAND = &H111 
' When the user clicks button Commandl, have a very simple popup menu appear. The 
' menu only has two options, divided by a separator bar. The menu is created when 


" needed and is 
' *** Place the 


' The following 
' identifiers used by 






































103 














destroyed after its use. 
following code inside a module. *** 


application-defined constants are used to name the menu item 
this example. They are not actually part of the API; instead, 


te "magic numbers." 


is a pointer to Forml's previous window procedure. 


"declaration" of the LOWORD API macro. 


they are 

' used just to eliminat 

Public Const ID_ABOUT = 101 
Public Const ID SEPARATOR = 102 
Public Const ID_EXIT = 

' This 

Public pOldProc As Long 

' This is actually the 

Public Function LOWORD 








' The 
' Spec 
Public 


dialog 




















(ByVal dwValue As Long) As Integer 


LOWORD = dwValue Mod &H10000 


End Function 

















Select Case uMsg 
Case WM_COMMAND 





" Do w 
Select 


hatever th 


following window procedure for window Forml handles its messages. 
ifically, it processes the WM_COMMAND message for the popup menu. 











Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 
Dim retval As Long ' return value 








Case LOWOR 


items on the popup menu requested. 








Case II 





D_ ABOUT 
" Use the 


' box. U 


D (wParam) 











VB MsgBox function to display a short message in a 








Sing the API isn't necessary. 





retval = MsgBox("This example demonstrates how to use the API 
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Case 


End 
End Function 








Private Sub 
Dim 


Dim 


im 
im 


im 














im 


Cr 





With 


End 
ret 
' Ad 
With 





CV 








Add 























"display a pop-up menu.", vbOkOnly Or vbInformation, 


"Windows API Guide") 








Case ID_EXIT 
' End this program by closing and unloading Forml. 
Unload Forml 
Case Else 
' Have the previous window procedure handle other items. 
retval = CallWindowProc(pOldProc, hWnd, uMsg, wParam, lParam) 
End Select 
WindowProc = 0 
Else 
' Pass this to the previous window procedure. 
WindowProc = CallWindowProc(pOldProc, hWnd, uMsg, wParam, lParam) 
Select 


Command1l1_ 


hPopupMe 
mii As M 


xxx Place the following code inside Forml. 


Click () 
nu As Long 
ENUITEMINE'O 














tpm As T 
curpos A 


PMPARAMS 





kkk 


handle to the popup menu to display 
describes menu items to add 


identifies the exclusion rectangle 





s POINT TYPI 


menusel As Long 


retval A 


eal 


s Long 








the me 
mii 

' Th 
«cbs 
' Wh 
.£Ma 
Th 





Th 


.fType 


holds the current mouse coordina 
ID of what the user selected in 
generic return value 


CES 











the popup menu 





te the popup menu that will be displayed. 
hPopupMenu = CreatePopupMenu () 








nu's 


e size of this st 
Len (mii) 


ize = 


first item: 


"About This Problem... 


tructure. 





ich elements of 
MIIM_STATI 


sk 
e type of it 
MFT_STI 








ture to use. 
D Or MIIM_TYPI 


the struc 
Or MIIM I 
a string. 





m 
Di 








tem: 
RING 





is item is currently enabled and is the default item. 











-£S 
' As 








ate = MFS 


ENA 





my 


BLED Or MFS_DEFAULT 




















Sign this i 





.WwWID 

v Di 

.dwT 

coh 
th 





Wit 





ID_ABOUT 
splay t 
ypeData = 











al 


= InsertMenultem (hPop 








d the se 


mii 





wtS 
wI 





D 


End With 


.fType 
tate 


cond item: 


he following tex 
"&About 
Len (.dwType!l 





tem an item identifier. 





for the item. 


Example..." 


la 





t This 
ta) 





Dat 





upMenu, 0, 1, mii) 


a separator bar. 





MFT_SI] 


EPA 


RATOR 








ENA 


G 











MFS_ 


BLED 








ID_SEPA 








RATOR 
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retval = InsertMenulItem(hPopupMenu, 1, 1, mii) 
' Add the final item: "Exit". 
With mii 
.£Type= MFT_STRING 
.wID = ID_EXIT 
.dwTypeData = "Eéxit" 
.cch = Len(.dwTypeData) 
End With 
retval = InsertMenulItem(hPopupMenu, 2, 1, mii) 


















































' Determine where the mouse cursor currently is, in order to have 








' the popup menu appear at that point. 
retval = GetCursorPos (curpos) 














' Make the exclusion rectangle empty because there's no need for it here. 


















































With tpm 
' Size of the structure. 
.cbSize = Len (tpm) 
' Make the exclusion rectangle empty. 
retval = SetRectEmpty(.rcExclude) 
End With 
' Display the popup menu at the mouse cursor. The window procedure 
' defined in the module will process the selected item automatically. 
menusel = TrackPopupMenuEx (hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or _ 
TPM_LEFTBUTTON, curpos.x, curpos.y, Forml.hWnd, tpm) 

















' Destroy the popup menu now. 
retval = DestroyMenu (hPopupMenu) 
End Sub 





' When Forml loads, tell it to use the custom window procedure. 
Private Sub Form_Load() 











' Set the custom window procedure to process Forml's messages. 











pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressO! 
End Sub 








' Before unloading, remove the custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














fF WindowProc) 


' Replace the previous window procedure to prevent crashing. 











retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
End Sub 








See Also 


WM_SYSCOMMAND 


Category 
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Menus 


Back to the Message list. 
Back to the Reference section. 





Last Modified: June 4, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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WWM_INITMENU Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


A window receives the WM_INITMENU message before one of its menus is displayed. This menu could be either the 
"regular" menu or the window's system menu. Upon receiving this message, the window should prepare the menu for display. 
This normally includes making sure any items that should be checked are checked, graying out certain items, etc. A window 
only receives WM_INITMENU when the user begins looking at a menu; it does not receive the message multiple times as the 
user looks into submenus. 


Return Value 


The WM_INITMENU message should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
A handle to the menu which will soon be displayed. 


lParam 
Not used. 


Constant Definitions 


Const WM_INITMENU = &H116 





Example 
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' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
's quite a few declarations for this example, but it's worth it! 


' There 
ublic 


ae) 


























Declare Function GetSystemMenu Lib "user32.d1l1" (ByVal hWnd As Long, ByVal 








bRevert _ 


ry 


ublic 
Long 
ublic 





AO) 





ublic 
ublic 
ublic 
ublic 
ublic 
ublic 





P 
P 
P 
Public 
P 
P 
P 
Public 
( 





tg 


ublic 





~ 


Public 





Public 
Public 
Public 
Public 
Public 
hWnd _ 


Public 


End Type 


ByVal _ 


As Long) As Long 








Declare Function GetMenulItemCount Lib "user32.d1l1" (ByVal hMenu As Long) As 











Type MENUITEMINFO 
cbhSize As Long 

fMask As Long 

fType As Long 

fState As Long 

wID As Long 

hSubMenu As Long 

hbmpChecked As Long 

hbmpUnchecked As Long 
dwItemData As Long 
dwTypeData As String 
cch As Long 


























TIM_STATE = &H1 
IIM_ID = &H2 
IIM_TYPE = &H10 





Con 
Con 
Con 
Con 
Con FT_STRING = &HO 
Con FS ENABLED = &HO 
Const MFS_ CHECKED = &H8 


























HO 2 ® © o 
sis Ss SiS Ss 





















































FT SEPARATOR = &H800 


Declare Function InsertMenulItem Lib "user32.d11" Alias "InsertMenuItemA" 








ByVal _ 











hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 














As MENUITEMINFO) As Long 
Declare Function SetMenulItemiInfo Lib "user32.d1l1" Alias "SetMenulItemInfoA" 

















ByVal _ 











hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 








As MENUITEMINFO) As Long 




















Declare Function SetWindowPos Lib "user32.d11" (ByVal hWnd As Long, ByVal _ 








hWndInsertAfter As Long, 

















ByVal x As Long, ByVal y As Long, ByVal cx As Long, 


cy As Long, ByVal wFlags As Long) As Long 





Const HWND_TOPMOST = -1 














Const HWND_NOTOPMOST = -2 





Const SWP_NOMOVE = &H2 
Const SWP_NOSIZE = &H1 























Declare Function SetWindowLong Lib "user32.d1l1" Alias "SetWindowLongA" (ByVal 














As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 








Const GWL_WNDPROC = -4 
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Ae) 





ublic Declare Function CallWindowProc Lib "user32.d1l1" Alias "CallWindowProcA" 
ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam _ 
As Long, ByVal lParam As Long) As Long 
Public Const WM SYSCOMMAND = &H112 
Public Const WM_INITMENU = ¢&H116 











~ 























' Add an option to make window Forml "Always On Top" to the bottom of its system 

' menu. A check mark appears next to this option when active. The menu item acts as 
a toggle. 

' Note how subclassing the window is necessary to process the two messages needed 

' to give the added system menu item its full functionality. 














' *** Place the following code in a module. *** 


Public pOldProc As Long ' pointer to Forml's previous window procedure 
Public ontop As Boolean ' identifies if Forml is always on top or not 




















' The following function acts as Forml's window procedure to process messages. 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam _ 



































As Long, ByVal lParam As Long) As Long 
Dim hSysMenu As Long ' handle to Forml's system menu 
Dim mii As MENUITEMINFO ' menu item information for Always On Top 
Dim retval As Long ' return value 


Select Case uMsg 

Case WM_INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 




































































With mii 
' Size of the structure. 
.cbSize = Len(mii) 
' Only use what needs to be changed. 
.fMask = MIIM_ STATE 
' If Forml is now always on top, check the item. 
.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenultemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 


Case WM SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 











top 
' setting of Forml to match. 
If wParam = 1 Then 





' Reverse the setting and make it the current one. 
ontop = Not ontop 
retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 





























HWND_NOTOPMOST), 
0, 0, O, 0, SWP_NOMOVE Or SWP_NOSIZI 
WindowProc = 0 








Cl 
<~ 





Else 
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' Some other item was selected. Let the previous window 














procedure 
' process it. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, 
lParam) 
End If 
Case Else 
' If this is some other message, let the previous procedure handle 
Ita 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 








End Select 
End Function 





xxx Place the following code inside Forml. *** 


' When Forml loads, add Always On Top to the system menu and set up the 




















new window procedure. 
Private Sub Form_Load() 
Dim hSysMenu As Long " handle to the system menu 
Dim count As Long ' the number of items initially on the menu 
Dim mii As MENUITEMINFO ' describes a menu item to add 
Dim retval As Long ' return value 





' Get a handle to the system menu. 
hSysMenu = GetSystemMenu(Forml.hWnd, 0) 

' See how many items are currently in it. 
count = GetMenultemCount (hSysMenu) 














' Add a separator bar and then Always On Top to the system menu. 












































With mii 
' The size of the structure. 
.cbSize = Len (mii) 
' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 
.fType = MFT_SEPARATOR 
' It has an ID of 0. 
.wID = 0 
End With 
' Add the separator to the end of the system menu. 
retval = InsertMenulItem(hSysMenu, count, 1, mii) 








' Likewise, add the Always On Top command. 
With mii 











Cl 


.fMask = MIIM_STATE Or MIIM_ID Or MIIM_ TYP] 
This is a regular text item. 

.fType = MFT_STRING 

' The option is enabled. 

-fState = MFS_ ENABLED 
' It has an ID of 1 (this identifies it in the window procedure). 
-wID = 1 

' The text to place in the menu item. 
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-dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenulItem(hSysMenu, count + 1, 1, mii) 














' Set the custom window procedure to process Forml's messages. 
ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 


End Sub 




















' Before unloading, restore the default system menu and remove the 
" custom window procedure. 
Private Sub Form_Unload(Cancel As Integer) 
Dim retval As Long ' return value 














' Replace the previous window procedure to prevent crashing. 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
' Remove the modifications made to the system menu. 
retval = GetSystemMenu(Forml.hWnd, 1) 
End Sub 
































Category 


Menus 


Back to the Message list. 
Back to the Reference section. 





Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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WM_SYSCOMMAND Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


A window receives the WM_SYSCOMMAND message when either the user selects an item from its system menu or the user 
presses the restore, maximize, minimize, or close button on its title bar. Typically, a program should let the default window 
procedure process this command, unless the program needs to respond to an item added by the program to the window's 
system menu (see the example below). 


Return Value 


The WM_SYSCOMMAND message should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 


The unique menu item identifier of the selected item. This could be one of the following flags, if the user selected an 
item that is by default on the system menu. When checking for these flags, first perform a bitwise And & HFFFO on 
wParam before checking its value. This is necessary because the lowest four bits are used internally by the system and 
do not affect the flag itself. Of course, if your program added its own items to the system menu, then wParam will be 
that item's identifier and not one of the following values. 
SC_CLOSE 

Close the window. 
SC_CONTEXTHELP 

Display a context-sensitive help window. 
SC_MAXIMIZE 

Maximize the window. 
SC_MINIMIZE 
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Minimize the window. 
SC_MOVE 
Move the window. 
SC_RESTORE 
Restore the window. 
SC_SIZE 
Size the window. 
lParam 
If the system menu item was selected using the mouse, this contains the coordinates of the mouse cursor. The x- 
coordinate is stored in the low-order word, and the y-coordinate is stored in the high-order word. The LOWORD and 


HIWORD macros can be used to extract the coordinates. 


Constant Definitions 







































































Const WM_SYSCOMMAND = &H112 
Const SC_CLOSE = &HF060 

Const SC_CONTEXTHELP = &HF180 
Const SC_MAXIMIZE = &HF030 
Const SC_MINIMIZE = &HF020 
Const SC_MOVE = &HF010 

Const SC_RESTORE = &HF120 
Const SC_SIZE = &HF000 

















Example 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 

' There's quite a few declarations for this example, but it's worth it! 

ublic Declare Function GetSystemMenu Lib "user32.d1l" (ByVal hWnd As Long, ByVal 











tg 











oO 


Revert _ 

As Long) As Long 

Public Declare Function GetMenultemCount Lib "user32.d11" (ByVal hMenu As Long) As 

Long 

Public Type MENUITEMINFO 
cbhSize As Long 

fMask As Long 

fType As Long 

fState As Long 
wID As Long 
hSubMenu As Long 
hbmpChecked As Long 
hbmpUnchecked As Long 
dwiItemData As Long 
dwTypeData As String 
cch As Long 

End Type 

Public Const MIIM_STATE = &H1 

Public Const MIIM_ID = &H2 
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Public Const MIIM_TYPE = &H10 
Public Const MFT_SEPARATOR = &H800 
Public Const MFT STRING = &HO 
Public Const MFS ENABLED = &HO 
Public Const MFS_ CHECKED = &H8 
Public Declare Function InsertMenulItem Lib "user32.d1l" Alias "InsertMenuItemA" 
(ByVal _ 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 
Public Declare Function SetMenulItemInfo Lib "user32.dl1" Alias "SetMenuItemInfoA" 
(ByVal _ 
hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii _ 
As MENUITEMINFO) As Long 
Public Declare Function SetWindowPos Lib "user32.dll1" (ByVal hWnd As Long, ByVal _ 
hWndInsertAfter As Long, ByVal x As Long, ByVal y As Long, ByVal cx As Long, 
ByVal _ 
cy As Long, ByVal wFlags As Long) As Long 





Public Const =I 
Public Const 
Public Const 
Public Const 
Public 


hWnd _ 


WND_TOPMOST 
WND_NOTOPMOST 
SWP_NOMOVI] & 
SWP_NOSTIZI & 
Declare Function SetWindowLong Lib "user32.d1ll1" Alias 























m 
Pi 
m 
Di 














"Se 











As Long, ByVal nIndex As Long, 
ublic Const GWL_WNDPROC -4 
ublic Declare Function CallWindowProc Lib 
ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, 
As Long, ByVal lParam As Long) As Long 
Public Const WM_SYSCOMMAND &H112 
Public Const WM INITMENU &H116 


ByVal dwNewLong As Long) 


ry 





gv 





"user32.dl1l1" Alias "C 











~ 








ByVal Msg As 














Add an option to make window Forml 
menu. 

toggle. 
Note how subclassing 
to give the added system menu item its full functionality. 


"Always On Top" to the bott 
A check mark appears next to this option when active. 














KK* 


xxx Place the following code in a module. 


' 


Public pOldProc 
Public ontop As 


As Long 
Boolean 


pointer to Forml's previous window pr 
identifies if Forml is always on top 























' The following function acts as Forml's window procedure to pro 
Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Lo 
As Long, ByVal lParam As Long) As Long 


Dim hSysMenu As Long 
Dim mii As MENUITEMINFO 
Dim retval As Long 


handle to Forml's system menu 
menu item information for Alw 























return value 


Select Case uMsg 
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tWindowLongA" 





(ByVal 
As Long 


allWindowProcA" 





Long, ByVal wParam _ 


om of its system 
The menu item acts as 





the window is necessary to process the two messages needed 


ocedure 
or not 


cess messages. 
ng, ByVal wParam _ 








ays On Top 
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Case WM _INITMENU 
' Before displaying the system menu, make sure that the Always On Top 
' option is properly checked. 
hSysMenu = GetSystemMenu (hwnd, 0) 







































































With mii 
' Size of the structure. 
.cbSize = Len(mii) 
' Only use what needs to be changed. 
.fMask = MIIM_ STATE 
' If Forml is now always on top, check the item. 
.fState = MFS_ENABLED Or IIf (ontop, MFS_CHECKED, 0) 
End With 
retval = SetMenulItemInfo(hSysMenu, 1, 0, mii) 
WindowProc = 0 


Case WM_SYSCOMMAND 
' If Always On Top (ID = 1) was selected, change the on top/not on 





top 





' setting of Forml to match. 
If wParam = 1 Then 





' Reverse the setting and make it the current one. 
ontop = Not ontop 
retval = SetWindowPos (hwnd, IIf (ontop, HWND_TOPMOST, 


























HWND_NOTOPMOST), 











0; O, 0, O, SWP_NOMOVE Or SWP_NOSTIZI 


Cl 
~~ 











WindowProc = 0 
Else 
' Some other item was selected. Let the previous window 
procedure 
' process it. 
WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, 
lParam) 
End If 








Case Else 
' If this is some other message, let the previous procedure handle 





it. 

WindowProc = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 
End Select 
End Function 











xxx Place the following code inside Forml. *** 


' When Forml loads, add Always On Top to the system menu and set up the 


























new window procedure. 
Private Sub Form_Load() 
Dim hSysMenu As Long " handle to the system menu 
Dim count As Long ' the number of items initially on the menu 
Dim mii As MENUITEMINFO ' describes a menu item to add 
Dim retval As Long " return value 


' Get a handle to the system menu. 
hSysMenu = GetSystemMenu(Forml.hWnd, 0) 








See how many items are currently in it. 
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count = GetMenultemCount (hSysMenu) 


i 





Add a separator bar and then Always 


On Top to the system menu. 



































































































































With mii 
' The size of the structure. 
.cbSize = Len (mii) 
' What parts of the structure to use. 
.fMask = MIIM_ID Or MIIM_TYPE 
' This is a separator. 
.fType = MFT_SEPARATOR 
' It has an ID of 0. 
.wID = 0 
End With 
' Add the separator to the end of the system menu. 
retval = InsertMenulItem(hSysMenu, count, 1, mii) 
' Likewise, add the Always On Top command. 
With mii 
.£fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE 
' This is a regular text item. 
.fType = MFT_STRING 
' The option is enabled. 
.fState = MFS_ENABLED 
' It has an ID of 1 (this identifies it in the window procedure). 
.wID = 1 
' The text to place in the menu item. 
.dwTypeData = "&Always On Top" 
.cch = Len(.dwTypeData) 
End With 
' Add this to the bottom of the system menu. 
retval = InsertMenulItem(hSysMenu, count + 1, 1, mii) 
' Set the custom window procedure to process Forml's messages. 
ontop = False 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 
End Sub 














Before unloading, 
custom window procedure. 
Private Sub Form_Unload(Cancel As 
Dim retval As Long 



































Pe 





restor 








retval 


$ 


= Se 


th 


default system menu and remove the 





Integer) 
return value 


Replace the previous window procedure to prevent crashing. 
tWindowLong (Forml.hWnd, GWL_WNDPROC, pOldProc) 














retval 


End Sub 





See Also 


WM_COMMAND 











Ge 


Remove the modifications made to the system menu. 
tSystemMenu (Forml.hWnd, 





1) 
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Category 


Menus 


Back to the Message list. 
Back to the Reference section. 








Last Modified: June 4, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 
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WM_LBUTTONDBLCLK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The WM_LBUTTONDBLCLK message tells a window that the left mouse button has been double-clicked while the 
cursor is inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure processes 
the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and MAKEPOINTS macros can be 


used to unpack the coordinate information easily. 


Return Value 


WM_LBUTTONDBLCLK should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_LBUTTONDBLCLK message. The DbIClick event handler 
provided by Visual Basic actually process WM_LBUTTONDBLCLK and unpacks some of the information passed with it 
for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
The left mouse button is down. 
MK _MBUTTON 
The middle mouse button is down. 
MK_RBUTTON 
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The right mouse button is down. 
MK_SHIFT 
The Shift key is down. 
MK_XBUTTONI1 
Windows 2000: The first X button is down. 
MK_XBUTTON2 
Windows 2000: The second X button is down. 
lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x-coordinate, and 
the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM_LBUTTONDBLCLK = &H203 
Const MK_CONTROL = &H8 

Const MK_LBUTTON = &H1 
Const MK_MBUTTON = &H10 
Const MK_RBUTTON = 
Const MK_SHIFT = &H4 
Const MK_XBUTTON1 = &H20 
Const MK_XBUTTON2 = &H40 
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Example 


This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the left mouse button has been 
' double-clicked in its center by sending the appropriate message to it. 











Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 


' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


Make Forml think the right mouse button was just double-clicked in that position. 





























retval = SendMessage(Forml.hWnd, WM _LBUTTONDOWN, ByVal CLlng(MK_LBUTTON) , ByVal 
packed) 

retval = SendMessage(Forml.hWnd, WM _LBUTTONUP, ByVal CLng(0), ByVal packed) 
retval = SendMessage(Forml.hWnd, WM_LBUTTONDBLCLK, ByVal CLng(MK_LBUTTON), ByVal 
packed) 
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retval = SendMessage(Forml.hWnd, WM LBUTTONUP, ByVal CLng(0), ByVal packed) 


See Also 


WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_RBUTTONDBLCLK 














Category 


Mouse 


Back to the Message list. 





Back to the Reference section. 
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WM_LBUTTONDOWN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The WM_LBUTTONDOWN message tells a window that the left mouse button has been pressed while the cursor 
is inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure 
processes the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_LBUTTONDOWN should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_LBUTTONDOWN message. The MouseDown event 
handler provided by Visual Basic actually process WM_LBUTTONDOWN and unpacks some of the information 
passed with it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
The left mouse button is down. 
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MK _MBUTTON 

The middle mouse button is down. 
MK_RBUTTON 

The right mouse button is down. 

MK_ SHIFT 

The Shift key is down. 

MK_XBUTTON1 

Windows 2000: The first X button is down. 
MK_XBUTTON2 

Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 


coordinate, and the high-order word contains the y-coordinate. 


Constant Definitions 








Const WM_LBUTTONDOWN = &H201 
Const MK_CONTROL = &H8 

Const MK _LBUTTON = &H1 

Const MK_MBUTTON = &H10 
Const MK_RBUTTON = &H2 

Const MK SHIFT = &H4 

Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 

















Example 


' This code is licensed according to the terms and conditions listed here. 





' Make window Forml think that the left mouse button has been 

' pressed in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 

















' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

" Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


' Make Forml think the left mouse button was just pressed in that position. 
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retval = SendMessage(Forml.hWnd, WM_LBUTTONDOWN, ByVal CLng(MK_LBUTTON), ByVal 
packed) 





See Also 


WM_LBUTTONDBLCLK, WM_LBUTTONUP, WM_MBUTTONDOWN, WM_RBUTTONDOWN 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_LBUTTONUP Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The WM_LBUTTONUP message tells a window that the left mouse button has been released while the cursor is 
inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure 
processes the message. When handling the message, the GET_X LPARAM, GET_Y LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_LBUTTONUP should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_LBUTTONUP message. The MouseUp event handler 
provided by Visual Basic actually process WM_LBUTTONUP and unpacks some of the information passed with 
it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_MBUTTON 
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The middle mouse button is down. 
MK_RBUTTON 
The right mouse button is down. 
MK_SHIFT 
The Shift key is down. 
MK_XBUTTONI1 
Windows 2000: The first X button is down. 
MK_XBUTTON2 
Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 
coordinate, and the high-order word contains the y-coordinate. 





Constant Definitions 


Const WM_LBUTTONUP = &H202 
Const MK _ CONTROL = &H8 
Const MK_MBUTTON = &H10 
Const MK _RBUTTON = &H2 
Const MK_SHIFT = &H4 

Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 














Example 


This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the left mouse button has been 

' released in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 





' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


Make Forml think the left mouse button was just released in that position. 
retval = SendMessage(Forml.hWnd, WM_LBUTTONUP, ByVal CLng(0), ByVal packed) 
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See Also 


WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_MBUTTONUP, WM_RBUTTONUP 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_MBUTTONDBLCLK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_MBUTTONDBLCLK message tells a window that the middle mouse button has been double-clicked while the 
cursor is inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure processes 
the message. When handling the message, the GET_X_LPARAM, GET_Y_LPARAM, and MAKEPOINTS macros can be 


used to unpack the coordinate information easily. 




















Return Value 


WM_MBUTTONDBLCLK should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 

The Ctrl key is down. 
MK_LBUTTON 

The left mouse button is down. 
MK_MBUTTON 

The middle mouse button is down. 
MK_RBUTTON 

The right mouse button is down. 
MK_SHIFT 

The Shift key is down. 
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MK_XBUTTON1 
Windows 2000: The first X button is down. 
MK_XBUTTON2 
Windows 2000: The second X button is down. 
lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x-coordinate, and 
the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM_MBUTTONDBLCLK = &H209 
Const MK_CONTROL = &H8 

Const MK_LBUTTON = &H1 
Const MK_MBUTTON = &H10 
Const MK_RBUTTON = &H2 
Const MK_SHIFT = &H4 
Const MK_XBUTTON1 = &H20 
Const MK_XBUTTON2 = &H40 
































Example 


This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the middle mouse button has been 

' double-clicked in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 











££ 


' First, get the coordinates of window Forml. 

















retval = GetWindowRect (Forml.hAWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


' Make Forml think the middle mouse button was just double-clicked in that position. 



























































retval = SendMessage(Forml.hWnd, WM MBUTTONDOWN, ByVal CLng(MK_MBUTTON) , ByVal 
packed) 

retval = SendMessage(Forml.hWnd, WM MBUTTONUP, ByVal CLng(0), ByVal packed) 
retval = SendMessage(Forml.hWnd, WM_MBUTTONDBLCLK, ByVal CLng(MK_MBUTTON), ByVal 
packed) 

retval = SendMessage(Forml.hWnd, WM MBUTTONUP, ByVal CLng(0), ByVal packed) 
See Also 
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WM_LBUTTONDBLCLK, WM_ MBUTTONDOWN, WM_MBUTTONUP, WM_RBUTTONDBLCLK 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_MBUTTONDOWN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_MBUTTONDOWN message tells a window that the middle mouse button has been pressed while the 
cursor is inside the window's client area. The information sent with the message identifies the cursor postion relative 


to the window as well as the state of various modifier keys and mouse buttons. The target window's window 
procedure processes the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_MBUTTONDOWN should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_MBUTTONDOWN message. The MouseDown event 
handler provided by Visual Basic actually process WM_MBUTTONDOWN and unpacks some of the information 
passed with it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
The left mouse button is down. 
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MK_MBUTTON 

The middle mouse button is down. 
MK_RBUTTON 

The right mouse button is down. 

MK_ SHIFT 

The Shift key is down. 

MK_XBUTTON1 

Windows 2000: The first X button is down. 
MK_XBUTTON2 

Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 


coordinate, and the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM_MBUTTONDOWN = &H207 
Const MK_CONTROL = &H8 

Const MK_LBUTTON &H1 
Const MK_MBUTTON = &H10 
Const MK_RBUTTON = &H2 
Const MK SHIFT = &H4 
Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 




















Example 


' This code is licensed according to the terms and conditions listed here. 





' Make window Forml think that the middle mouse button has been 

' pressed in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 

















' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

" Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


' Make Forml think the middle mouse button was just pressed in that position. 
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retval = SendMessage(Forml.hWnd, WM_MBUTTONDOWN, ByVal CLng(MK_MBUTTON), ByVal 
packed) 





See Also 


WM_LBUTTONDOWN, WM_MBUTTONDBLCLK, WM_MBUTTONUP, WM_RBUTTONDOWN 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_MBUTTONUP Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_MBUTTONUP message tells a window that the middle mouse button has been released while the cursor 
is inside the window's client area. The information sent with the message identifies the cursor postion relative to the 
window as well as the state of various modifier keys and mouse buttons. The target window's window procedure 
processes the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_MBUTTONUP should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_MBUTTONUP message. The MouseUp event handler 
provided by Visual Basic actually process WM_MBUTTONUP and unpacks some of the information passed with 
it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
The left mouse button is down. 
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MK_RBUTTON 

The right mouse button is down. 

MK_SHIFT 

The Shift key is down. 

MK_XBUTTONI1 

Windows 2000: The first X button is down. 
MK_XBUTTON2 

Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 





coordinate, and the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM_MBUTTONUP = &H208 
Const MK_CONTROL = &H8 
Const MK _LBUTTON = &H1 
Const MK_RBUTTON = &H2 
Const MK SHIFT = &H4 

Const MK_XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 

















Example 


' This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the middle mouse button has been 
' released in its center by sending the appropriate message to it. 

















Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 


' First, get the coordinates of window Forml. 

















retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


' Make Forml think the middle mouse button was just released in that position. 
retval = SendMessage(Forml.hWnd, WM_MBUTTONUP, ByVal CLng(0), ByVal packed) 
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See Also 


WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_RBUTTONUP 





Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_MOUSEMOVE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The WM_MOUSEMOVE message tells a window that the position of the mouse cursor inside of its boundaries 
has moved. The information sent with the message identifies the cursor postion relative to the window as well as 
the state of various modifier keys and mouse buttons. The target window's window procedure processes the 

message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and MAKEPOINTS macros 


can be used to unpack the coordinate information easily. 


Return Value 


WM_MOUSEMOVE should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_MOUSEMOVE message. The MouseMove event 
handler provided by Visual Basic actually process WM_MOUSEMOVE and unpacks some of the information 
passed with it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
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The left mouse button is down. 
MK_MBUTTON 
The middle mouse button is down. 
MK_RBUTTON 
The right mouse button is down. 
MK_ SHIFT 
The Shift key is down. 
MK_XBUTTONI 
Windows 2000: The first X button is down. 
MK_XBUTTON2 

Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 
coordinate, and the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM_MOUSEMOVE = &H200 
Const MK CONTROL &H8 
Const MK_LBUTTON = &H1 
Const MK _MBUTTON = &H10 
Const MK_RBUTTON &H2 
Const MK_SHIFT = &H4 
Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 

















Example 


' This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the mouse cursor has moved into its 

' center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 





' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 
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' Make Forml think the cursor just moved to that position. 
retval = SendMessage(Forml.hWnd, WM_MOUSEMOVE, ByVal CLng(0), ByVal packed) 





Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_RBUTTONDBLCLK Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_RBUTTONDBLCLK message tells a window that the right mouse button has been double-clicked while the 
cursor is inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure processes 
the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and MAKEPOINTS macros can be 


used to unpack the coordinate information easily. 


Return Value 


WM_RBUTTONDBLCLK should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 

A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_ CONTROL 

The Ctrl key is down. 
MK_LBUTTON 

The left mouse button is down. 
MK_MBUTTON 

The middle mouse button is down. 
MK_RBUTTON 

The right mouse button is down. 
MK_SHIFT 
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The Shift key is down. 
MK_XBUTTONI1 
Windows 2000: The first X button is down. 
MK_XBUTTON2 
Windows 2000: The second X button is down. 
lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x-coordinate, and 
the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM _RBUTTONDBLCLK = &H206 
Const MK_CONTROL = &H8 

Const MK_LBUTTON = &H1 
Const MK_MBUTTON = &H10 
Const MK_RBUTTON = 
Const MK_SHIFT = &H4 
Const MK_XBUTTON1 = &H20 
Const MK_XBUTTON2 = &H40 








Z 
| 
Q 
jam 
N 























Example 


This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the right mouse button has been 
' double-clicked in its center by sending the appropriate message to it. 








Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 





' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


Make Forml think the right mouse button was just double-clicked in that position. 









































retval = SendMessage(Forml.hWnd, WM RBUTTONDOWN, ByVal CLlng(MK_RBUTTON) , ByVal 
packed) 

retval = SendMessage(Forml.hWnd, WM RBUTTONUP, ByVal CLng(0), ByVal packed) 
retval = SendMessage(Forml.hWnd, WM_RBUTTONDBLCLK, ByVal CLng(MK_RBUTTON), ByVal 
packed) 

retval = SendMessage(Forml.hWnd, WM RBUTTONUP, ByVal CLng(0), ByVal packed) 








http://216.26.168.92/vbapi/ref/w/wm_rbuttondbliclk.html (2 of 3) [9/1/2002 6:09:51 PM] 


Windows API Guide: WM_RBUTTONDBLCLK Message 
See Also 


WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_RBUTTONDOWN Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_RBUTTONDOWN message tells a window that the right mouse button has been pressed while the 
cursor is inside the window's client area. The information sent with the message identifies the cursor postion relative 


to the window as well as the state of various modifier keys and mouse buttons. The target window's window 
procedure processes the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_RBUTTONDOWN should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_RBUTTONDOWN message. The MouseDown event 
handler provided by Visual Basic actually process WM_RBUTTONDOWN and unpacks some of the information 
passed with it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
The left mouse button is down. 
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MK_MBUTTON 

The middle mouse button is down. 
MK_RBUTTON 

The right mouse button is down. 

MK_ SHIFT 

The Shift key is down. 

MK_XBUTTON1 

Windows 2000: The first X button is down. 
MK_XBUTTON2 

Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 


coordinate, and the high-order word contains the y-coordinate. 


Constant Definitions 


Const WM _RBUTTONDOWN = &H204 
Const MK_CONTROL = &H8 

Const MK_LBUTTON &H1 
Const MK_MBUTTON = &H10 
Const MK_RBUTTON = &H2 
Const MK SHIFT = &H4 
Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 




















Example 


' This code is licensed according to the terms and conditions listed here. 





' Make window Forml think that the right mouse button has been 

' pressed in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 

















' First, get the coordinates of window Forml. 











retval = GetWindowRect (Forml.hWnd, winrect) 

" Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


' Make Forml think the right mouse button was just pressed in that position. 
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retval = SendMessage (Forml.hWnd, WM_RBUTTONDOWN, ByVal CLng(MK_RBUTTON), ByVal 
packed) 





See Also 


WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDBLCLK, WM_RBUTTONUP 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_RBUTTONUP Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The WM_RBUTTONUP message tells a window that the right mouse button has been released while the cursor is 
inside the window's client area. The information sent with the message identifies the cursor postion relative to the 


window as well as the state of various modifier keys and mouse buttons. The target window's window procedure 
processes the message. When handling the message, the GET_X_ LPARAM, GET_Y_ LPARAM, and 
MAKEPOINTS macros can be used to unpack the coordinate information easily. 








Return Value 


WM_RBUTTONUP should always return 0. 


Visual Basic-Specific Issues 


It is not necessary to create a special hander for the WM_RBUTTONUP message. The MouseUp event handler 
provided by Visual Basic actually process WM_RBUTTONUP and unpacks some of the information passed with 
it for easier use. 


Parameters 


wParam 
A combination of the following flags specifying which modifer keys, if any, are currently depressed: 
MK_CONTROL 
The Ctrl key is down. 
MK_LBUTTON 
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The left mouse button is down. 
MK_MBUTTON 
The middle mouse button is down. 
MK_ SHIFT 
The Shift key is down. 
MK_XBUTTONI1 
Windows 2000: The first X button is down. 
MK_XBUTTON2 
Windows 2000: The second X button is down. 





lParam 
The (x,y) coordinates of the mouse cursor relative to the window. The low-order word contains the x- 
coordinate, and the high-order word contains the y-coordinate. 





Constant Definitions 


Const WM_RBUTTONUP = &H205 
Const MK CONTROL = &H8 
Const MK_LBUTTON = &H1 
Const MK_MBUTTON = &H10 
Const MK_SHIFT = &H4 
Const MK _XBUTTONI1 = &H20 
Const MK_XBUTTON2 = &H40 

















Example 


This code is licensed according to the terms and conditions listed here. 


' Make window Forml think that the right mouse button has been 

' released in its center by sending the appropriate message to it. 

Dim xcoord As Long, ycoord As Long ' x and y coordinates of the faked cursor 
position 

Dim packed As Long ' the coordinates "packed" into a single 32-bit integer 
Dim winrect As RECT ' receives coordinates of the window 

Dim retval As Long ' return value 





' First, get the coordinates of window Forml. 








retval = GetWindowRect (Forml.hWnd, winrect) 

' Use the coordinates to calculate the midpoint of Forml. 

xcoord = (winrect.right - winrect.left) / 2 

ycoord = (winrect.bottom - winrect.top) / 2 

' Now pack the coordinates into the appropriate words of the value 
packed = (ycoord * &H10000) + xcoord 


Make Forml think the right mouse button was just released in that position. 
retval = SendMessage(Forml.hWnd, WM_RBUTTONUP, ByVal CLng(0), ByVal packed) 
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See Also 


WM_LBUTTONUP, WM_MBUTTONUP, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN 


Category 


Mouse 


Back to the Message list. 
Back to the Reference section. 
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WM_TIMER Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


A window receives the WM_TIMER message when the time-out period of a timer (created by the SetTimer function) elapses. 
You should only create a handler for this message if you did not specify a TimerProc callback function for the timer. 
Otherwise, allow the window's default message handler to invoke the TimerProc function. 


Return Value 


The WM_TIMER message should always return 0. 


Visual Basic-Specific Issues 


None. 


Parameters 


wParam 
The unique identifier of the timer that sent the message. 
lParam 
A pointer to the TimerProc callback function that should be invoked. If no function is specified, this will be 0. 





Constant Definitions 





Const WM_TIMER = &H113 











Example 


Display the current time in text box control Textl. The time is updated twice every second, and the time is formatted according 
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to the current locale's settings. To use this example, place a text edit box named Text! on a form window. 


' This code is licensed according to the tern 





' Declarations and such needed for the example: 








































































































ns and conditions listed here. 










































































' (Copy them to the (declarations) section of a module.) 
Public Type SYSTEMTIME 
wYear As Integer 
wMonth As Integer 
wDayOfWeek As Integer 
wDay As Integer 
wHour As Integer 
wMinute As Integer 
wsecond As Integer 
wMilliseconds As Integer 
End Type 
Public Declare Function SetTimer Lib "user32.d11" (ByVal hWnd As Long, ByVal nIDEvent 
As Long, ByVal uElapse As Long, ByVal lpTimerFunc As Long) As Long 
Public Declare Function KillTimer Lib "user32.d1l1" (ByVal hWnd As Long, ByVal 
niDEvent As Long) As Long 
Public Const WM_TIMER = ¢&H113 
Public Declare Function GetTimeFormat Lib "kernel32.d11" Alias "GetTimeFormatA" 
(ByVal _ 
Locale As Long, ByVal dwFlags As Long, lpTime As SYSTEMTIME, ByVal lpFormat 
As Any, _ 
ByVal lpTimeStr As String, ByVal cchTime As Long) As Long 
Public Declare Function SetWindowLong Lib "user32.d11" Alias "SetWindowLongA" (ByVal 
hWnd _ 
As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long 
Public Const GWL_WNDPROC = -4 
Public Declare Function CallWindowProc Lib "user32.d1ll" Alias "CallWindowProcA" 
(ByVal _ 
lpPrevWndFunc As Long, ByVal hWnd As Long, ByVal Msg As Long, ByVal wParam As 
Long, 
ByVal lParam As Long) As Long 


' *** Place the 


' A pointer to Forml's dei 








Pubic pOldProc As Long 


' The 





Long, 


following 
' actually processes WM_TIME 
Public Function WindowProc ( 





following code inside a module. 





function will handle all of Forml's messages. 





ByVal 1P 
Dim systime As S 





Dim timestr As S 
Dim slength As L 





Select Case uMsg 


KkK* 


fault window procedure: 








T 








ByVal hWnd As Long, 


aram As Long) 

















ByVal uMsg As Long, 
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formatted string 
length of formatted string returned 


It only 
R and passes all others to the default handler. 
ByVal wParam As 
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Case WM_TIMER 
' Retrieve the current time, according to the computer's time zone. 
GetLocalTime systime 











' Format a string to represent the time. 
slength = GetTimeFormat(0, 0, systime, CLng(0), timestr, 








Len(timestr) ) 





' Display the string in Textl, found on window Forml. 
Forml.Textl.Text = Left(timestr, slength) 

WindowProc = 0 
Case Else 

' Pass the message to Forml's previous procedure. 

WindowProc = CallWindowProc(pOldProc, hWnd, uMsg, wParam, lParam) 
End Select 
End Function 





























' *** Place the following code inside Forml. *** 





' Create the timer when the form opens and destroy it when the form closes. 

' The timer is given an ID of 1, so the return values don't need to be saved. 

' Also, set up the window procedure when the form is loaded, and remove it 

' when the form is unloaded. This procedure will receive all of Forml's messages. 
Private Sub Forml_Load() 

Dim retval As Long ' return value 




















pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 
retval = SetTimer(Forml.hWnd, 1, 500, AddressOf TimerProc) 
End Sub 














Private Sub Forml_Unload(Cancel As Integer) 
Dim retval As Long ' return value 





retval = KillTimer(Forml.hWnd, 1) 
retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 
End Sub 











See Also 


SetTimer 


Category 


Timers 


Back to the Message list. 





Back to the Reference section. 
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WM_CLOSE Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the WM_CLOSE message to a window, naturally enough, instructs it to close. Some windows will prompt the user 
with a confirmation dialog box before it closes, while others will close immediately. Exactly what happens depends on the 
program. Just keep in mind that sending WM_CLOSE merely asks the window to close -- there's no guarantee that will 
actually happen. 


Return Value 


This message should always return zero. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to zero. 
lParam 


Not used -- set to zero. 


Constant Definitions 


Const WM_CLOSE = &H10 





Example 


Let the user enter the title of a window in a text box. Then, attempt to close the window whose title bar matches that text when 
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the user clicks a button. To use this example, place a text boxed named txtTitle and a command button named cmdClose on a 
form window. 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function SendMessage Lib "user32.dl1" Alias "SendMessageA" (ByVal hWnd 

















As Long, ByVal _ 
Msg As Long, wParam As Any, lParam As Any) As Long 

Public Const WM_CLOSE = &H10 

Public Declare Function FindWindow Lib "user32.d1ll" Alias "FindWindowA" (ByVal 

lpClassName As String, 

ByVal lpWindowName As String) As Long 

















' xxx Place the following code inside the form window. *** 


Private Sub cmdClose_Click () 
Dim hWnd As Long ' handle of the window to try to close 
Dim result As Long ' result of the message 




















' Get a handle to the window whose title the user entered. 
hWnd = FindWindow(vbNullString, txtTitle.Text) 
If hWnd <> 0 Then 
' Ask the window to close. 
result = SendMessage (hWnd, WM_CLOSE, ByVal CLng(0), ByVal CLng(0)) 


Debug.Print "Told " & txtTitle.Text & " to close." 


























Else 














' Couldn't find the window the user specified. 
Debug.Print "Unable to find window titled " & txtTitle.Text & "." 








End If 











End Sub 





See Also 


Destroy Window 


Category 


Back to the Function list. 
Back to the Reference section. 








Last Modified: December 17, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/w/wm_close.html 








http://216.26.168.92/vbapi/ref/w/wm_close.html (2 of 2) [9/1/2002 6:10:06 PM] 


Windows API Guide: WM_GETTEXT Message 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





WM_GETTEXT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Send the WM_GETTEXT message to a window to retrieve that window's text. For regular windows, this text is the text 
displayed in the title bar caption area. The target window's text is copied to a text buffer supplied in the message parameters. 
The message is handled by the target window's default window procedure. 


Return Value 


The message returns the number of characters retrieved, not counting the terminating null character. 


Visual Basic-Specific Issues 


When using SendMessage to send the WM_GETTEXT message, the ByVal keyword must be used in front of both the 
wParam and lParam parameters. 


Parameters 


wParam 

The number of characters to copy from the target window's text, including the necessary terminating null character. 
lParam 

The string which receives the first wParam characters (minus one for the null) of the target window's text. 


Constant Definitions 





Const WM_GETTEXT = &HD 














Example 
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' This code is licensed according to the terms and conditions listed here. 


' Display the title bar text of window Forml by sending the 



































' appropriate messages to it. 
Dim wintext As String ' receives the copied text from the target window 
Dim slength As Long ' length of the window text 

Dim retval As Long ' return value of message 

' First, determine how much space is necessary for the buffer. 


' (1 is added for the terminating null character.) 

slength = SendMessage(Forml.hWnd, WM_GETTEXTLENGTH, ByVal CLng (0), ByVal CLng(0)) 
' Make enough room in the buffer to receive the text. 

wintext = Space(slength) 

' Copy the target window's text into the buffer. 

retval = SendMessage(Forml.hWnd, WM_GETTEXT, ByVal slength, ByVal wintext) 

' Remove the terminating null and extra space from the buffer. 

































































wintext = Left (wintext, retval) 
' Display the result. 
Debug.Print "Forml's title bar text is: "; wintext 





See Also 


GetWindowText, WM_GETTEXTLENGTH, WM_SETTEXT 


Category 


Windows 


Back to the Message list. 
Back to the Reference section. 
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WM_GETTEXTLENGTH Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Send the WM_GETTEXTLENGTH message to a window to discover the number of characters in that window's text. This 
character count does not include the terminating null character. In some cases, this message will report a larger number of 


characters than what actually exists; however, the count obtained by this message will always be no less than the actual 
number of characters. The WM_GETTEXTLENGTH message is handled by the target window's default window procedure. 


Return Value 


The message returns the number of characters in the target window's text, not including the terminating null. 


Visual Basic-Specific Issues 


When using SendMessage to send the WM_GETTEXTLENGTH message, both the wParam and lParam parameters must be 
set using the expression ByVal CLng(0). 


Parameters 
wParam 

Not used -- set to 0. 
lParam 


Not used -- set to 0. 


Constant Definitions 




















Const WM_GETTEXTLENGTH = &HE 


Example 
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' This code is licensed according to the terms and conditions listed here. 

















' Display the title bar text of window Forml by sending the 
' appropriate messages to it. 























Dim wintext As String ' receives the copied text from the target window 
Dim slength As Long ' length of the window text 

Dim retval As Long ' return value of message 

' First, determine how much space is necessary for the buffer. 














' (1 is added for the terminating null character.) 

slength = SendMessage(Forml.hWnd, WM_GETTEXTLENGTH, ByVal CLng (0), ByVal CLlng(0)) + 
' Make enough room in the buffer to receive the text. 

wintext = Space(slength) 

' Copy the target window's text into the buffer. 

retval = SendMessage(Forml.hWnd, WM_GETTEXT, ByVal slength, ByVal wintext) 

' Remove the terminating null and extra space from the buffer. 



























































wintext = Left (wintext, retval) 
' Display the result. 
Debug.Print "Forml's title bar text is: "; wintext 


See Also 


GetWindowTextLength, WM_GETTEXT 


Category 


Windows 


Back to the Message list. 
Back to the Reference section. 


Last Modified: January 27, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
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WM_HELP Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.51 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


The WM_HELP message instructs a window to display context-sensitive help. This help could refer to the window itself, 
one of the controls on it, or a child window or dialog it created. The message includes a structure identifying the object 
which generated the message. While a window does not necessarily have to respond to the WM_HELP message by 
opening a WinHelp document, it ought to display help information of some kind. 


Return Value 


The WM_HELP message should always return a non-zero value. 


Visual Basic-Specific Issues 


None. 
Parameters 
wParam 

Not used -- set to 0. 
lParam 


A pointer to a HELPINFO structure identifying the control or other window which originated the message. 





Constant Definitions 


Const WM_HELP = &H53 


Example 
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' This code is licensed according to the terms and conditions listed here. 


' Display an HTML document to provide help when the 

' user clicks the "Help" button of a dialog box. Notice how 

' the WM_HELP message must be handled explicitly in 

' this example, since Visual Basic does not allow you to create 

' a handler through the interface. Pay careful attention to where each 
' piece of code must go. 

















' *** Place the following code in a module. *** 
' This is a pointer to Forml's previous window procedure. 
Public pOldProc As Long 


' This is the handler for the WM_HELP message. 
Public Function WindowProc(ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam As 


Long, ByVal lParam As Long) As Long 

















Dim hi As HELPINFO ' information about window requesting help 
Dim slength As Long ' length of string 

Dim wintext As String ' text of window calling for help 

Dim retval As Long ' return value 

' Decide which message has been received. 


Select Case uMsg 
Case WM_HELP 
" Determine if the message box, having text "Warning!", is 
' requesting help. If so, display an HTML document for help. 
' NOTE: in a "real" program, you should use the 
' MessageBoxIndirect function because it 
' allows a Context ID for a WinHelp file to be specified. But 
' since this is an example for WM_HELP, this inferior 
' method is presented. 


























" Copy the information about the help message into the structure. 
CopyMemory hi, ByVal lParam, Len (hi) 





" Determine the text of the window for which help is requested. 
slength = GetWindowTextLength(hi.hItemHandle) + 1 























wintext = Space (slength) 

retval = GetWindowText (hi.hItemHandle, wintext, slength) 
wintext = Left (wintext, retval) 

' Tf it is "Warning!", open up the proper HTML document. 
If wintext = "Warning!" Then 








Wwe Wwe 
r d 


retval = ShellExecute (hwnd, "open", "C:\MyProg\mboxhelp.html", 


SM_RESTORE) 
End If 








' Return successfully. 
WindowProc = 1 
Case Else 
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' Let the previous message handler process this message. 
retval = CallWindowProc(pOldProc, hwnd, uMsg, wParam, lParam) 





WindowProc = retval 
End Select 
End Function 


' *** Place the following code in the Forml_Load procedure. *** 
' Set our custom window procedure as Forml's procedure. 
pOldProc = SetWindowLong(Forml.hWnd, GWL_WNDPROC, AddressOf WindowProc) 











' *** Place the following code in the Forml_Unload procedure. *** 

' Set the previous procedure as the one Forml uses (to make VB happy). 
Dim retval As Long 

retval = SetWindowLong(Forml.hWnd, GWL_WNDPROC, pOldProc) 











' *** Place the following code wherever you want to invoke the message box. 
' Prompt the user for a selection, allowing him to get help 
' about his choice. 

Dim mbresult As Long ' result of message box 

Dim flags As Long ' message box's flags 














flags = MB_YESNO Or MB_HELP Or MB_ICONWARNING 




















mbresult = MessageBox(Forml.hWnd, "Are you sure?", "Warning!", flags) 
If mbresult = IDYES Then 
Debug.Print "You said 'Yes'" 
Else 
Debug.Print "You said 'No'" 
End If 





Category 


Windows 


Back to the Message list. 
Back to the Reference section. 
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WM_SETTEXT Message 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Requires Windows CE 1.0 or later. 


Description & Usage 


Sending the WM_SETTEXT message to a window sets that window's text. For ordinary windows, the text is 
the text that appears in the title bar. The message is handled by the target window's default window procedure. 


Return Value 


If the message returns 0, an error occured. If the message returns a non-zero value, the window text was 
successfully set. 


Visual Basic-Specific Issues 


When sending the WM_SETTEXT message, the expression By Val CLng(0) must be used for the wParam 
parameter. Additionally, the ByVal keyword must also preceed the string passed as the /Param parameter. 


Parameters 
wParam 

Not used -- set to 0. 
lParam 


The string to set as the window text. 


Constant Definitions 
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Const WM_SETTEXT = &HC 


Example 


' This code is licensed according to the terms and conditions listed here. 


' Set the title bar text of window Forml to "Caption Area". 
" Do this by sending the proper message to a window. 

Dim wintext As String ' string to set as the window's text 
Dim retval As Long ' return value of message 








' Store the desired text in a string. 
wintext = "Caption Area" 
' Send a message telling window Forml to make that string its text. 





f 


retval = SendMessage(Forml.hWnd, WM_SETTEXT, ByVal CLng(0), ByVal wintext) 








' Display the result of the message. 

If retval = 0 Then 

Debug.Print "Unable to set the text of Forml." 

Else 

Debug.Print "The text of Forml was successfully set." 
End If 














See Also 


SetWindowText, WM _GETTEXT 


Category 


Windows 


Back to the Message list. 
Back to the Reference section. 





Last Modified: January 25, 2000 
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


http://216.26.168.92/vbapi/ref/w/wm_settext.html (2 of 3) [9/1/2002 6:10:28 PM] 


Windows API Guide: WM_SETTEXT Message 


This page is at http://www.vbapi.com/ref/w/wm_settext.html 





http://216.26.168.92/vbapi/ref/w/wm_settext.html (3 of 3) [9/1/2002 6:10:28 PM] 


Windows API Guide: Reference: Messages 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








Windows API Reference: Messages 


Last Update: January 21, 2001 
Number of Messages Listed: 66 (6 added) 


Below is an alphabetical list of the API messages currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to: AIBICIDIEIFIGIHIIIJIKILIMINIOIPIQIRISITIUIVIWIXIYIZ 


o BM_CLICK 

o BM_GETCHECK 
o BM_GETSTATE 
o BM_SETCHECK 
o BM_SETSTATE 


o CB_ADDSTRING 

o CB_DELETESTRING 

o CB_GETCOUNT 

o CB_GETCURSEL 

o CB_GETDROPPEDSTATE 

o CB_GETLBTEXT 

o CB_GETLBTEXTLEN 

o CB_INSERTSTRING 

o CB_RESETCONTENT 

o CB_SETCURSEL 

o CB_SHOWDROPDOWN 
e E 
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e M 


e W 


EM_CANUNDO 
EM_GETFIRSTVISIBLELINE 
EM_GETLINE 
EM_GETPASSWORDCHAR 
EM_GETSEL 
EM_LINEINDEX 
EM_LINELENGTH 
EM_REPLACESEL 
EM_SETPASSWORDCHAR 
EM_SETSEL 

EM_UNDO 


IPM_CLEARADDRESS 
IPM_GETADDRESS 
IPM_ISBLANK 
IPM_SETADDRESS 
IPM_SETFOCUS 
IPM_SETRANGE 


LB_ADDSTRING 
LB_DELETESTRING 
LB_GETCOUNT 
LB_GETCURSEL NEW 
LB_GETSEL NEW 
LB_GETSELCOUNT NEW 
LB_GETSELITEMS NEW 
LB_GETTEXT 
LB_GETTEXTLEN 
LB_INSERTSTRING 
LB_RESETCONTENT 
LB_SETCURSEL NEW 
LB_SETSEL NEW 


MM_MCINOTIFY 


WM_CLOSE 
WM_COMMAND 
WM_GETTEXT 
WM_GETTEXTLENGTH 
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o WM_HELP 

o WM_INITMENU 

o WM_LBUTTONDBLCLK 
o WM_LBUTTONDOWN 
o WM_LBUTTONUP 

o WM_MBUTTONDBLCLK 
o WM_MBUTTONDOWN 
o WM_MBUTTONUP 

o WM_MOUSEMOVE 

o WM_RBUTTONDBLCLK 
o WM_RBUTTONDOWN 
o WM_RBUTTONUP 

o WM_SETTEXT 

o WM_SYSCOMMAND 

o WM_TIMER 


Go back to the Reference section index. 
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Go back to the Windows API Guide home page. 

E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/msga.html 


http://216.26.168.92/vbapi/ref/msga.html (3 of 3) [9/1/2002 6:11:08 PM] 


Windows API Guide: Reference: Callback Functions 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 








Windows API Reference: Callback 
Functions 


Last Update: January 21, 2001 
Number of Callback Functions Listed: 15 (0 added) 


Below is an alphabetical list of the API callback functions currently documented on this web site. Please 
keep in mind that this site does not encompass the entire API yet, so unfortunately may not find what you 
are looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to: AIBICIDIEIFIGIHITIJIKILIMINIOIPIQIRISITIUIVIWIXIYIZ 


e B 

o BrowseCallbackProc 
e C 

o CCHookProc 

o CFHookProc 
e E 

o EnumChildProc 

o EnumFontFamExProc 

o EnumFontFamProc 

o EnumThreadWndProc 

o EnumWindowsProc 
e M 

o MsgBoxCallback 
e O 

o OFNHookProc 

o OFNHookProcOldStyle 
e P 
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o PropEnumProcEx 
e S 


o SoundSentryProc 
e T 

o TimerProc 
e W 

o WindowProc 


Go back to the Reference section index. 
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BrowseCallbackProc Callback Function 


Public Function BrowseCallbackProc(ByVal hwnd As Long, ByVal uMsg As Long, ByVal 
lParam As Long, ByVal lpData As Long) As Long 

' application-defined code goes here 
End Function 





Description & Usage 


The BrowseCallbackProc callback function process the messages of a Browse for Folder dialog box. Specifically, this 





function responds to the messages notifying when the dialog box is being initialized and when the user as changed the 
current selection. This function does not necessarily have to be called BrowseCallbackProc; that is merely the name 
given to it in discussions about the API. The callback function can work with the dialog box by sending it one of the 
following messages via SendMessage: 


BFFM_ENABLEOK 
Enable or disable the dialog box's OK button. To enable the OK button, set the /Param message parameter to a 
non-zero value. To disable the OK button, set the lParam message parameter to 0. 

BFFM_SETSELECTION 
Set the current selection in the dialog box. To specify the desired path using a string, set the /Param message 
parameter to the string and the wParam message parameter to a non-zero value. To specify the desired path 
using a pointer to an ITEMIDLIST structure (a.k.a. a PIDL), set the /Param message parameter to the PIDL and 


the wParam message parameter to 0. 

BFFM_SETSTATUSTEXT 
Set the status text displayed by the dialog box, if it exists. Set the /Param message parameter to the string 
holding the desired text. 


Return Value 


The function always returns 0, unless the dialog box is processing the BFFM_VALIDATEFAILED message (see that 
message's description below for details). 


Visual Basic-Specific Issues 


Like all callback functions, BrowseCallbackProc must be declared Public within a module. 


Parameters 
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hwnd 
A handle to the Browse for Folder dialog box calling this function. This handle is necessary to send messages 
back to the dialog box. 
uMsg 
One of the following flags specifying the event: 
BFFM_INITIALIZED 
The dialog box has just finished initializing. lParam is Q. 
BFFM_SELCHANGED 
The user has changed the current selection. /Param is a PIDL to the current selection. 
BFFM_VALIDATEFAILED 
With Internet Explorer 4.0 or later: The user has typed an invalid path into the edit box. /Param is a 
pointer to a null-terminated string holding the invalid path name. The function should return 0 to close 
the dialog box, or a non-zero value to keep it displayed. 
lParam 
Depends on the value of uMsg. 
lpData 


The application-defined value given in the BROWSEINFO structure used to create the dialog box. 


Constant Definitions 


Const BFFM_ENABLEOK = &H465 
Const BFFM_SETSELECTION = &H466 
Const BFFM_SETSTATUSTEXT = &H464 
Const BFFM_INITIALIZED = 1 

Const BFFM_SELCHANGED = 2 

Const BFFM_VALIDATEFAILED = 3 


Used By 


BROWSEINFO 








Go back to the Callback Function listing. 
Go back to the Reference section index. 
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CCHookProc Callback Function 


Public Function CCHookProc (ByVal hdlg As Long, ByVal uiMsg As Long, ByVal wParam As 
Long, ByVal lParam As Long) As Long 

' application-defined code goes here 
End Function 








Description & Usage 


CCHookProc is used to process a Choose Color common dialog box's messages. This hook function allows a program to 
write its own code to process messages otherwise handled by the Choose Color box. The function does not have to be 
named CCHookProc -- that is merely the name given to it in discussions about the API. 


Return Value 


If the function returns 0, the Choose Color dialog box's default message handler processes the message. If the function 
returns a non-zero value, the Choose Color dialog box's default message handler does not receive the message. 


Visual Basic-Specific Issues 


Like all callback functions, CCHookProc must be declared Public and be defined in a module. 


Parameters 


hdlg 
A handle to the Choose Color dialog box which the message is for. 
uiMsg 
The message to be acted upon. 
wParam 
Additional information about the message. 
lParam 
Additional information about the message. 


Used By 


CHOOSECOLOR_TYPE 


Go back to the Callback Function listing. 
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Go back to the Reference section index. 
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CFHookProc Callback Function 


Public Function CFHookProc (ByVal hdlg As Long, ByVal uiMsg As Long, ByVal wParam As 
Long, ByVal lParam As Long) As Long 

' application-defined code goes here 
End Function 











Description & Usage 


CFHookProc is used to process a Choose Font common dialog box's messages. This hook function allows a program to 
write its own code to process messages otherwise handled by the Choose Font box. The function does not have to be named 
CFHookProc -- that is merely the name given to it in discussions about the API. 


Return Value 


If the function returns 0, the Choose Font dialog box's default message handler processes the message. If the function 
returns a non-zero value, the Choose Font dialog box's default message handler does not receive the message. 


Visual Basic-Specific Issues 


Like all callback functions, CFHookProc must be declared Public and be defined in a module. 


Parameters 


hdlg 
A handle to the Choose Font dialog box which the message is for. 
uiMsg 
The message to be acted upon. 
wParam 
Additional information about the message. 
lParam 
Additional information about the message. 


Used By 


CHOOSEFONT_TYPE 


Go back to the Callback Function listing. 
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Go back to the Reference section index. 
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EnumChildProc Callback Function 


Public Function EnumChildProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 
' application-defined code goes here 
End Function 





Description & Usage 


EnumChildProc is an application-defined callback function used by EnumChildWindows for each window 
enumerated. This function should process the window in whatever manner is required. This function does not 
necessarily have to be named EnumChildProc -- that is merely the name given to it in discussions about the API. 


Return Value 


If the function returns 0, EnumChildWindows will immediately stop enumerating child windows. If the function 
returns a non-zero value, EnumChildWindows will continue enumerating child windows until it can no longer find any. 


Visual Basic-Specific Issues 


Like all callback functions, EnumChildProc must be declared Public and be defined in a module. 


Parameters 
hwnd 
A handle to the window which EnumChildWindows has just found. 


lParam 
Whatever value was specified in the parameter list of EnumChildWindows. 


Used By 


EnumChildWindows 








Go back to the Callback Function listing. 
Go back to the Reference section index. 
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EnumFontFamExProc Callback Function 














Public Function EnumFontFamExProc (ByVal lpelfe As Long, ByVal lpntme As Long, ByVal 
FontType As Long, ByVal lParam As Long) As Long 

' application-specific code goes her 
End Function 





Description & Usage 


The EnumFontFamExProc callback function processes each font enumerated by EnumFontFamiliesEx. The function 
receives a large amount of information describing both the logical font attributes as well as its metrics. Information 
describing TrueType fonts is received by the function in a slightly different format than non-TrueType font information. This 


function does not necessarily have to be named EnumFontFamExProc -- that is simply the name given to it in discussions 
about the Windows API. 








Return Value 


If the function returns 0, EnumFontFamiliesEx immediately stops enumerating fonts. If the function returns a non-zero value, 
EnumFontFamiliesEx continues enumerating fonts as long as another one can be found. 








Visual Basic-Specific Issues 


Like all callback functions, EnumFontFamExProc must be declared Public and be defined in a module. 


Parameters 


Ipelfe 
A pointer to an ENUMLOGFONTEX structure describing the logical attributes of the font. 
Ipntme 
If the font is a TrueType font, this is a pointer to a NEWTEXTMETRICEX structure. If the font is not a TrueType 
font, this is a pointer to a TEXTMETRIC structure. Either structure describes the text metrics of the font. 
FontType 
A combination of the following flags (although usually only one is used) identifying the type of font: 
DEVICE_FONTTYPE 
The font is a device font. 
RASTER_FONTTYPE 
The font is a raster font. 
TRUETYPE_FONTTYPE 
The font is a TrueType font. 














[Param 
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Additional data specified by EnumFontFamiliesEx. 





Constant Definitions 


Const DEVICE_FONTTYPE = &H2 
Const RASTER_FONTTYPE = &H1 
Const TRUETYPE_FONTTYPE = &H4 


Used By 


EnumFontFamiliesEx 











Go back to the Callback Function listing. 
Go back to the Reference section index. 
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EnumFontFamProc Callback Function 


Public Function EnumFontFamProc (ByVal lpelf As Long, ByVal lpntm As Long, ByVal 
FontType As Long, ByVal lParam As Long) As Long 

' application-specific code goes here 
End Function 





Description & Usage 


The EnumFontFamProc callback function processes each font enumerated by EnumFontFamilies. The function 








receives a large amount of information describing both the logical font attributes as well as its metrics. Information 
describing TrueType fonts is received by the function in a slightly different format than non-TrueType font 
information. This function does not necessarily have to be named EnumFontFamProc -- that is simply the name given 
to it in discussions about the Windows API. 


Return Value 


If the function returns 0, EnumFontFamilies immediately stops enumerating fonts. If the function returns a non-zero 
value, EnumFontFamilies continues enumerating fonts as long as another one can be found. 





Visual Basic-Specific Issues 


Like all callback functions, EnumFontFamProc must be declared Public and be defined in a module. 


Parameters 


lpelf 
A pointer to an ENUMLOGFONT structure describing the logical attributes of the font. 
lpntm 
If the font is a TrueType font, this is a pointer to a NEWTEXTMETRIC structure. If the font is not a TrueType 
font, this is a pointer to a TEXTMETRIC structure. Either structure describes the text metrics of the font. 
FontType 
A combination of the following flags (although usually only one is used) identifying the type of font: 
DEVICE_FONTTYPE 
The font is a device font. 
RASTER_FONTTYPE 
The font is a raster font. 
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TRUETYPE_FONTTY PE 
The font is a TrueType font. 
lParam 
Additional data specified by EnumFontFamilies. 


Constant Definitions 


Const DEVICE_FONTTYPE = &H2 
Const RASTER_FONTTYPE = &H1 
Const TRUETYPE_FONTTYPE = &H4 


Used By 


EnumFontFamilies 


Go back to the Callback Function listing. 
Go back to the Reference section index. 
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EnumThreadWndProc Callback Function 


Public Function EnumThreadWndProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 
' application-defined code goes her 
End Function 











Description & Usage 


EnumThreadWndProc is an application-defined callback function used by EnumThread Windows for each window 
enumerated. This function should process the window in whatever manner is required. This function does not necessarily 
have to be named EnumThreadWndProc -- that is merely the name given to it in discussions about the API. 








Return Value 


If the function returns 0, EnumThreadWindows will immediately stop enumerating thread windows. If the function returns a 
non-zero value, EnumThreadWindows will continue enumerating thread windows until it can no longer find any. 











Visual Basic-Specific Issues 


Like all callback functions, EnumThreadWndProc must be declared Public and be defined in a module. 


Parameters 
hwnd 
A handle to the window which EnumThreadWindows has just found. 


lParam 
Whatever value was specified in the parameter list of EnumThreadWindows. 


Used By 


EnumThreadWindows 





Go back to the alphabetical Function listing. 
Go back to the Reference section index. 
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EnumWindowsProc Callback Function 


Public Function EnumWindowsProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 
' application-defined code goes here 
End Function 





Description & Usage 


EnumWindowsProc is an application-defined callback function used by EnumWindows for each window enumerated. 








This function should process the window in whatever manner is required. This function does not necessarily have to be 
named EnumWindowsProc -- that is merely the name given to it in discussions about the API. 


Return Value 


If the function returns 0, EnumWindows will immediately stop enumerating windows. If the function returns a non-zero 





value, EnumWindows will continue enumerating windows until it can no longer find any. 


Visual Basic-Specific Issues 


Like all callback functions, EnumWindowsProc must be declared Public and be defined in a module. 


Parameters 


hwnd 

A handle to the window which EnumWindows has just found. 
lParam 

Whatever value was specified in the parameter list of EnumWindows. 


Used By 





EnumWindows 


Go back to the Callback Function listing. 
Go back to the Reference section index. 
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MsgBoxCallback Callback Function 


Public Sub MsgBoxCallback (lpHelpInfo As HELPINFO) 
' application-defined code goes here 
End Sub 





Description & Usage 


The MsgBoxCallback callback function processes help events generated by a message box. It receives 


information about what context-sensitive help information to display to the user. Like all callback 
functions, this function does not need to be named MsgBoxCallback inside your program. 
MsgBoxCallback is merely the name given to it in discussions about the Windows API. 


Return Value 


MsgBoxCallback does not return a value. 


Visual Basic-Specific Issues 


Like all callback functions, MsgBoxCallback must be declared Public and be defined in a module. 


Parameters 


lpHelpInfo 
Identifies what help information to display to the user. 


Used By 


MSGBOXPARAMS 
Back to the Callback Function list. 
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OFNHookProc Callback Function 


Public Function OFNHookProc (ByVal hdlg As Long, ByVal uiMsg As Long, ByVal wParam As 
Long, _ 














ByVal lParam As Long) As Long 
' Application-defined code goes her 
End Function 











Description & Usage 


The OFNHookProc hook function processes messages for an Open File or Save File common dialog box. This callback 


function works with file dialogs that have Windows Explorer-type extensions. For file dialogs without these extensions, use 
OFNHookProcOldStyle instead. 





Return Value 


If the function returns zero, the default file dialog message handler processes the message. If the function returns a nonzero 
value, the default file dialog message handler ignores the message. 


Visual Basic-Specific Issues 


Like most callback functions, this function must be Public and be defined in a module. It does not need to be named 
OFNHookProc in your program -- that is the name given to it in discussions about the API. 


Parameters 


hdlg 
A handle to the file dialog's child window. Use GetParent to get a handle to the actual file dialog box. 
uiMsg 
The identifier of the message to process. 
wParam 
The first message parameter. 
lParam 
The second message parameter. 


Used By 


OPENFILENAME 





Back to the Callback Function list. 
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OFNHookProcOldStyle Callback Function 


Public Function OFNHookProcOldStyle (ByVal hdlg As Long, ByVal uiMsg As Long, ByVal 
wParam As Long, 





ByVal lParam As Long) As Long 
' Application-defined code goes her 
End Function 





Description & Usage 


The OFNHookProcOldStyle hook function processes messages for an Open File or Save File common dialog box. This 
callback function works with file dialogs that do not have Windows Explorer-type extensions. For file dialogs with these 
extensions, use ORFNHookProc instead. 





Return Value 


If the function returns zero, the default file dialog message handler processes the message. If the function returns a nonzero 
value, the default file dialog message handler ignores the message. 


Visual Basic-Specific Issues 


Like most callback functions, this function must be Public and be defined in a module. It does not need to be named 
OFNHookProcOldStyle in your program -- that is the name given to it in discussions about the API. 


Parameters 


hdlg 
A handle to the file dialog's child window. Use GetParent to get a handle to the actual file dialog box. 





uiMsg 

The identifier of the message to process. 
wParam 

The first message parameter. 
lParam 

The second message parameter. 


Used By 


OPENFILENAME 
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shop.com | 
PropEnumProcEx Callback Function 
Public Function PropEnumProcEx (ByVal hwnd As Long, ByVal lpszString As Long, ByVal 








=y 


Data As Long, ByVal dwData As Long) As Long 
' application-defined code goes here 
End Function 





Description & Usage 


The PropEnumProcEx callback function is used to process an enumerated window property gotten by the EnumPropsEx 
function. Each window property is passed one at a time to this callback function. This callback function receives not only 
the property's name but also a handle to its data (whatever the object happens to be). In your program, this function does not 
actually have to be called PropEnumProcEx -- that is merely the name used for it in discussions regarding the API. 


Return Value 


If the function returns 0, EnumPropsEx immediately terminates window property enumeration. If the function returns a non- 
zero value, EnumPropsEx will continute enumeration until the last property is found. 


Visual Basic-Specific Issues 


Like all callback functions, PropEnumProcEx must be Public and be declared inside a module. 


Parameters 


hwnd 

A handle to the window whose properties are being enumerated. 
IpszString 

A pointer to a string specifying the name of the window property. 
hData 

A handle to the window property's data. 
dwData 

Additional data specified by EnumPropsEx. 


Used By 


EnumPropsEx 
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SoundSentryProc Callback Function 


Public Function SoundSentryProc (ByVal dwMillisec As Long, ByVal fwdEffect As Long) 
As Long 

' application-defined code goes here 
End Function 








Description & Usage 


SoundSentryProc allows the use of a custom cue used by the SoundSentry accessibility feature. This callback function 
defines a custom method to use to present some sort of visual cue in place of the ones built into SoundSentry. Unlike most 
callback functions, this function must be called SoundSentryProc and must be exported by a DLL which is loaded on 
startup. 


Return Value 


If the function returns 0, the function failed to display the visual cue. If the function returns a non-zero value, the function 
displayed the cue successfully. 


Visual Basic-Specific Issues 


None. 


Parameters 


dwMillisec 
The duration in milliseconds over which the visual cue should be displayed. 
fdwEffect 
The type of visual cue to display. The only valid value for this parameter is SSWF_CUSTOM. 


Constant Definitions 


Const SSWF_CUSTOM = 4 


Used By 


SOUNDSENTRY 





http://216.26.168.92/vbapi/ref/s/soundsentryproc.html (1 of 2) [9/1/2002 6:12:38 PM] 


Windows API Guide: SoundSentryProc Callback Function 


Go back to the Callback Function listing. 
Go back to the Reference section index. 


Last Modified: August 15, 1999 
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 


Go back to the Windows API Guide home page. 
E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 


This page is at http://www.vbapi.com/ref/s/soundsentryproc.html 











http://216.26.168.92/vbapi/ref/s/soundsentryproc.html (2 of 2) [9/1/2002 6:12:38 PM] 


Windows API Guide: TimerProc Callback Function 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | www.vbapi.com | www.vb- 
shop.com | 





TimerProc Callback Function 








Public Sub TimerProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal idEvent As Long, 


ByVal dwTime As Long) 
' Place application-defined code here. 
End Sub 


Description & Usage 


The TimerProc callback function executes whenever the time-out period of an active timer elapses. Because the callback 





function receives the index of the timer that called it, a single TimerProc function can be used to handle multiple timers 
simultaneously. 


Return Value 


TimerProc does not return a value. 


Visual Basic-Specific Issues 


Like all callback functions, TimerProc must be Public and be declared inside a module. 


Parameters 


hwnd 
A handle to the window that owns the timer, if any. 
uMsg 
This always specifies the WM_TIMER message. 
idEvent 
The unique identifier of the timer that is calling the function. 
dwTime 
The number of milliseconds that have elapsed since Windows was last started. This is the same as the output from the 
GetTickCount function. 


Constant Definitions 


Const WM_TIMER = &H113 


Used By 
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SetTimer 


Back to the Callback Function list. 
Back to the Reference section. 
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WindowProc Callback Function 


Public Function WindowProc (ByVal hwnd As Long, ByVal uMsg As Long, ByVal wParam As 
Long, ByVal lParam As Long) As Long 

' application-defined code goes here 
End Function 





Description & Usage 


The WindowProc hook function acts as the window procedure of a window. The window procedure processes all of the 
messages received by that window. The function does not actually have to be named WindowProc; that is just the name 
given to it in discussions about the API. 


Return Value 


The return value depends on the requirements of the message being processed. 


Visual Basic-Specific Issues 


Like all callback functions, WindowProc must be declared Public and be defined in a module. 





Parameters 


hwnd 
A handle to the window which has received the message. 
uMsg 
The message to be acted upon. 
wParam 
Additional information about the message. 
lParam 
Additional information about the message. 


Used By 


CallWindowProc, GetClassLong, GetWindowLong, SetClassLong, SetWindowLong, WNDCLASS, WNDCLASSEX 


Go back to the Callback Function listing. 
Go back to the Reference section index. 
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Windows API Reference: Macros 


Last Update: January 21, 2001 
Number of Macros Listed: 15 


Below is an alphabetical list of the API macros currently documented on this web site. Please keep in 
mind that this site does not encompass the entire API yet, so unfortunately may not find what you are 
looking for. To suggest any additions you would like to see made, please contact the author with your 
request. All pages added since the last update of this site are clearly marked with NEW. 


Jump to 


>AIBICIDIEIFIGIHITIJIKILIMINIOIPIQIRISITIUIVIWIXIYIZ 


FIRST _IPADDRESS 
FOURTH_IPADDRESS 


GET_X_LPARAM 
GET_Y_ LPARAM 


HIBYTE 
HIWORD 


LOBYTE 
LOWORD 


MAKELANGID 
MAKELCID 
MAKEIPRANGE 
MAKEPOINTS 
MAKEWORD 
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o SECOND_IPADDRESS 
o T 
o THIRD IPADDRESS 


Go back to the Reference section index. 
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FIRST_IPADDRESS Macro 


Public Function FIRST_IPADDRESS (ByVal ipAddress As Long) As Long 
FIRST_IPADDRESS = Val("&H" & Left (Right ("O0000000" & Hex(ipAddress), 8), 2)) 
End Function 














Description & Usage 


FIRST_IPADDRESS extracts the first field (field 0) from an IP address packed inside a 32-bit integer. The IP address must 
be in host byte order. 


Return Value 


The macro returns the value of the first field of the IP address. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical computation, it is 
necessary to implement FIRST_IPADDRESS this way in VB. Other methods to perform this task can fail for large inputs 
because VB interprets them as negative values, which causes an equivalent mathematical computation to return an unwanted 
value. 


Parameters 


ipAddress 
The IP address to get the first field of. The IP address must be packed into a 32-bit integer in host byte order. 


See Also 
FOURTH IPADDRESS, SECOND _IPADDRESS, THIRD IPADDRESS 


Back to the Macro list. 
Back to the Reference section. 
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FOURTH_IPADDRESS Macro 


Public Function FOURTH_IPADDRESS (ByVal ipAddress As Long) As Long 
FOURTH_IPADDRESS = Val("&H" & Right ("00" & Hex(ipAddress), 2)) 
End Function 


Description & Usage 


FOURTH_IPADDRESS extracts the fourth field (field 3) from an IP address packed inside a 32-bit 
integer. The IP address must be in host byte order. 


Return Value 


The macro returns the value of the fourth field of the IP address. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical 
computation, it is necessary to implement FOURTH_IPADDRESS this way in VB. Other methods to 
perform this task can fail for large inputs because VB interprets them as negative values, which causes an 
equivalent mathematical computation to return an unwanted value. 


Parameters 


ipAddress 
The IP address to get the fourth field of. The IP address must be packed into a 32-bit integer in 
host byte order. 


See Also 


FIRST_IPADDRESS, SECOND_IPADDRESS, THIRD_IPADDRESS 
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GET X LPARAM Macro 


Public Function GET_X_LPARAM (ByVal lParam As Long) As Long 
Dim hexstr As String 
hexstr = Right ("00000000" & Hex(lParam), 8) 
GET_X_LPARAM = CLng("&H" & Right (hexstr, 4)) 

End Function 


Description & Usage 


The GET_X_LPARAM macro extracts the x-coordinate from a 32-bit integer packed with a coordinate 
pair. The macro retrieves the value found in the value's low-order word, which in this case represents the 
x-coordinate. 


Return Value 


The macro returns the x-coordinate of the packed coordinate pair. 


Visual Basic-Specific Issues 


The method I present for extracting the low-order word may seem unusual, since I first convert the value 
into an 8-digit hex string and then cut that in half. I do this because it is the only way that works 100% of 
the time in Visual Basic. All the math-based routines I've seen to do this fail when the &H80000000 bit 
of lParam is set, because VB then sees it as a negative number. 


Parameters 


lParam 
The packed coordinate pair to extract the x-coordinate from. 


See Also 
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GET_Y_LPARAM, MAKEPOINTS 


Back to the Macro list. 
Back to the Reference section. 
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GET Y LPARAM Macro 


Public Function GET_Y_LPARAM (ByVal lParam As Long) As Long 
Dim hexstr As String 
hexstr = Right ("00000000" & Hex(lParam), 8) 
GET_Y_ LPARAM = CLng("&H" & Left(hexstr, 4)) 
End Function 


Description & Usage 


The GET_Y_LPARAM macro extracts the y-coordinate from a 32-bit integer packed with a coordinate 
pair. The macro retrieves the value found in the value's high-order word, which in this case represents the 
y-coordinate. 


Return Value 


The macro returns the y-coordinate of the packed coordinate pair. 


Visual Basic-Specific Issues 


The method I present for extracting the high-order word may seem unusual, since I first convert the value 
into an 8-digit hex string and then cut that in half. I do this because it is the only way that works 100% of 
the time in Visual Basic. All the math-based routines I've seen to do this fail when the &H80000000 bit 
of lParam is set, because VB then sees it as a negative number. 


Parameters 


lParam 
The packed coordinate pair to extract the y-coordinate from. 


See Also 


http://216.26.168.92/vbapi/ref/g/get_y_lparam.html (1 of 2) [9/1/2002 6:13:28 PM] 


Windows API Guide: GET_Y_LPARAM Macro 


GET_X_LPARAM, MAKEPOINTS 


Back to the Macro list. 
Back to the Reference section. 


Last Modified: July 30, 2000 

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 
Go back to the Windows API Guide home page. 

E-mail: vbapi@vbapi.com Send Encrypted E-Mail 

This page is at http://www.vbapi.com/ref/g/get_y_Iparam.html 


http://216.26.168.92/vbapi/ref/g/get_y_lparam.html (2 of 2) [9/1/2002 6:13:28 PM] 


Windows API Guide: HIBYTE Macro 


vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 





HIBYTE Macro 


Public Function HIBYTE(ByVal wValue As Integer) As Byte 
HIBYTE = Val("G&H" & Left (Right ("O000" & Hex(wValue), 4), 2)) 
End Function 


Description & Usage 


HIBYTE extracts the high-order byte of a 16-bit integer (a word). 


Return Value 


The macro returns the high-order byte of the value passed to it. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical 
computation, it is necessary to implement HIBYTE this way in VB. Other methods to perform this task 
can fail for large inputs because VB interprets them as negative values, which causes an equivalent 
mathematical computation to return an unwanted value. 


Parameters 


wValue 
The 16-bit integer to extract the high-order byte of. 


See Also 
LOBYTE, MAKEWORD 
Back to the Macro list. 
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HIWORD Macro 


Public Function HIWORD (ByVal dwValue As Long) As Long 
Dim hexstr As String 
hexstr = Right ("O0000000" & Hex(dwValue), 8) 
HIWORD = CLlng("&H" & Left (hexstr, 4)) 

End Function 


Description & Usage 


The HIWORD macro isolates the high-order word from a 32-bit integer. 


Return Value 


The macro returns the high-order word of the 32-bit integer passed to it. 


Visual Basic-Specific Issues 


The method I present for extracting the high-order word may seem unusual, since I first convert the value 
into an 8-digit hex string and then cut that in half. I do this because it is the only way that works 100% of 
the time in Visual Basic. All the math-based routines I've seen to do this fail when the &H80000000 bit 
of dwValue is set, because VB then sees it as a negative number. 


Parameters 


dwValue 
The 32-bit integer to extract the high-order word from. 


See Also 


LOWORD 
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LOBYTE Macro 


Public Function LOBYTE(ByVal wValue As Integer) As Byte 
LOBYTE = Val("&H" & Right ("00" & Hex(wValue), 2)) 
End Function 


Description & Usage 


LOBYTE extracts the low-order byte of a 16-bit integer (a word). 


Return Value 


The macro returns the low-order byte of the value passed to it. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical 
computation, it is necessary to implement LOBYTE this way in VB. Other methods to perform this task 
can fail for large inputs because VB interprets them as negative values, which causes an equivalent 
mathematical computation to return an unwanted value. 


Parameters 


wValue 
The 16-bit integer to extract the low-order byte of. 


See Also 
HIBYTE, MAKEWORD 
Back to the Macro list. 
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LOWORD Macro 


Public Function LOWORD (ByVal dwValue As Long) As Long 
Dim hexstr As String 
hexstr = Right ("O00000000" & Hex(dwValue), 8) 
LOWORD = CLng("&H" & Right (hexstr, 4)) 

End Function 


Description & Usage 


The LOWORD macro isolates the low-order word from a 32-bit integer. 





Return Value 


The macro returns the low-order word of the 32-bit integer passed to it. 


Visual Basic-Specific Issues 


The method I present for extracting the low-order word may seem unusual, since I first convert the value 
into an 8-digit hex string and then cut that in half. I do this because it is the only way that works 100% of 
the time in Visual Basic. All the math-based routines I've seen to do this fail when the &H80000000 bit 
of dwValue is set, because VB then sees it as a negative number. 


Parameters 


dwValue 
The 32-bit integer to extract the low-order word from. 


See Also 


HIWORD 
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MAKELANGID Macro 


Public Function MAKELANGID (ByVal usPrimaryLanguage As Integer, ByVal usSubLanguage 
As Integer) As Long 

MAKELANGID = (usSubLanguage * 1024) Or usPrimaryLanguage 
End Function 


















































Description & Usage 


The MAKELANGID macro creates a language identifier. This language identifier specifies a language using a "primary" 
language (for example, English, Spanish, French, etc.) and a "sublanguage” or dialect of that language (for example, American 
English, Australian English, UK English, etc.). Keep in mind that a typical installation of Windows only supports one primary 
language besides the neutral language, so only a few of the language identifiers generated by MAKELANGID will be 
supported on any given computer. 


Note that the following language/sublanguage combinations have special meanings: 


e LANG NEUTRAL and SUBLANG_NEUTRAL: A neutral language, supported by any installation of Windows. 
e LANG _ NEUTRAL and SUBLANG_DEFAULT: The user's default language. 
e LANG NEUTRAL and SUBLANG_SYS_DEFAULT: The system's default language. 


Return Value 


The macro returns the language identifier that represents the specified primary language and sublanguage. 


Visual Basic-Specific Issues 


None. 


Parameters 


usPrimaryLanguage 
One LANG_* flag specifying the primary language. Valid flags can be found in the Constant Definitions section 
below. If using a user-defined primary language, this can be any value between &H200 and &H3FF inclusive. 
usSubLanguage 
One SUBLANG * flag specifying the sublanguage. Valid flags can be found in the Constant Definitions section 
below. If using a user-defined sublanguage, this can be any value between &H20 and &H3F inclusive. 


Constant Definitions 
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Note: Both the possible flags for usPrimaryLanguage and usSubLanguage appear below. Since the function of each flag is so 
obvious given its name, they are presented below without annotation. 


























































































































































































































































































































































































































































































































Const LANG_NEUTRAL = &HO 
Const LANG_AFRIKAANS = &H36 
Const LANG _ALBANTAN = &HI1C 
Const LANG ARABIC = &H1 
Const LANG BASQUE = &H2D 
Const LANG BELARUSIAN = &H23 
Const LANG_BULGARIAN = &H2 
Const LANG _CATALAN = &H3 
Const LANG_CHINESE = &H4 
Const LANG CROATIAN = &H1A 
Const LANG_CZECH = &H5 

Const LANG _DANISH = &H6 
Const LANG_DUTCH = &H13 
Const LANG_ENGLISH = &H9 
Const LANG ESTONIAN = &H25 
Const LANG _FAEROESE = &H38 
Const LANG_FARSI = &H29 
Const LANG_FINNISH = &HB 
Const LANG_FRENCH = &HC 
Const LANG_GERMAN = &H7 
Const LANG _GREEK = &H8 

Const LANG _ HEBREW = &HD 
Const LANG_HINDI = &H39 
Const LANG _HUNGARIAN = &HE 
Const LANG_ICELANDIC = &HF 
Const LANG_INDONESIAN = &H21 
Const LANG_ITALIAN = &H10 
Const LANG_JAPANESE = &H11 
Const LANG_KOREAN = &H12 
Const LANG_LATVIAN = &H26 
Const LANG_LITHUANIAN = &H27 
Const LANG_MACEDONIAN = &H2F 
Const LANG_MALAY = &H3E 
Const LANG NORWEGIAN = &H14 
Const LANG POLISH = &H15 
Const LANG_PORTUGUESE = &H16 
Const LANG_ROMANIAN = &H18 
Const LANG_RUSSIAN = &H19 
Const LANG_SERBIAN = &HI1A 
Const LANG_SLOVAK = &H1B 
Const LANG_SLOVENIAN = &H24 
Const LANG_SPANISH = &HA 
Const LANG SWAHILI = &H41 
Const LANG_SWEDISH = &H1D 
Const LANG_THAT = &HI1E 

Const LANG _TURKISH = &H1F 
Const LANG _UKRANIAN = &H22 
Const LANG_VIETNAMESE = &H2A 
Const SUBLANG_NEUTRAL = &HO 
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Const SUBLANG_DEFAULT = &H1 

Const SUBLANG_SYS_DEFAULT = &H2 
Const SUBLANG_ARABIC = &H1 

Const SUBLANG_ARABIC_IRAQ = &H2 
Const SUBLANG_ARABIC_EGYPT = &H3 
Const SUBLANG_ARABTC_LIBYA = &H4 
Const SUBLANG_ARABTC_ALGERIA = &H5 
Const SUBLANG_ARABIC_MOROCCO = &H6 
Const SUBLANG_ARABIC_TUNISIA = &H7 
Const SUBLANG_ARABIC_OMAN = &H8 
Const SUBLANG_ARABIC_YEMEN = &H9 
Const SUBLANG_ARABIC_SYRIA = &HA 
Const SUBLANG_ARABTIC_JORDAN = &HB 
Const SUBLANG_ARABTIC_LEBANON = &HC 
Const SUBLANG_ARABIC_KUWAIT = &HD 
Const SUBLANG_ARABIC_UAE = &HE 
Const SUBLANG_ARABIC_BAHRAIN = &HF 
Const SUBLANG_ARABIC_QATAR = &H10 
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Con 


PORTUGUESE_BRAZILIAN = &H1 
_SPANISH = &H1 


UBLAN 
UBLAN 
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st S G 
Const SUBLANG_CHINESE TRADITIONAL = &H1 
Const SUBLANG_ CHINESE SIMPLIFIED = &H2 
Const SUBLANG_ CHINESE HONGKONG = &H3 
Const SUBLANG CHINESE SINGAPORE = &H4 
Const SUBLANG_DUTCH = &H1 
Const SUBLANG_DUTCH_BELGIAN = &H2 
Const SUBLANG_ENGLISH_US = &H1 
Const SUBLANG_ ENGLISH _UK = &H2 
Const SUBLANG_ ENGLISH _AUS = &H3 
Const SUBLANG_ENGLISH_ CAN = &H4 
Const SUBLANG_ENGLISH_NZ = &H5 
Const SUBLANG_ENGLISH_EIRE = &H6 
Const SUBLANG_ENGLISH_SAFRICA = &H7 
Const SUBLANG_ENGLISH_ JAMAICA = &H8 
Const SUBLANG_ENGLISH_CARRIBEAN = &H9 
Const SUBLANG_FRENCH = &H1 
Const SUBLANG_FRENCH_BELGIAN = &H2 
Const SUBLANG_FRENCH_CANADIAN = &H3 
Const SUBLANG_FRENCH_SWISS = &H4 
Const SUBLANG_ FRENCH LUXEMBOURG = &H5 
Const SUBLANG_GERMAN = &H1 
Const SUBLANG_GERMAN_ SWISS = &H2 
Const SUBLANG_ GERMAN AUSTRIAN = &H3 
Const SUBLANG_ GERMAN LUXEMBOURG = &H4 
Const SUBLANG_GERMAN LIECHTENSTEIN = &H5 
Const SUBLANG_ITALIAN = &H1 
Const SUBLANG_ITALIAN SWISS = &H2 
Const SUBLANG_KOREAN = &H1 
Const SUBLANG_ KOREAN _JOHAB = &H2 
Const SUBLANG_ NORWEGIAN BOKMAL = &H1 
Const SUBLANG_ NORWEGIAN NYNORSK = &H2 
Const SUBLANG_ PORTUGUESE = &H2 

st S G 

st S G 
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Const SUBLANG_SPANISH_ MEXICAN = &H2 
Const SUBLANG_SPANISH_ MODERN = &H3 
Const SUBLANG_SPANISH_ GUATEMALA = &H4 
Const SUBLANG_SPANISH_COSTARICA = &H5 
Const SUBLANG_SPANISH_ PANAMA = &H6 























Con UBLANG_SPANISH_DOMINICAN = &H7 




































































Const SUBLANG_SPANISH_ VENEZUELA = &H8 
Con BLANG_SPANISH_ COLOMBIA = &H9 
Const SUBLANG_SPANISH_PERU = &HA 
Const SUBLANG_SPANISH_ARGENTINA = &HB 
Const SUBLANG_SPANISH_ECUADOR = &HC 
Const SUBLANG_SPANISH_CHILE = &HD 
Const SUBLANG_SPANISH_URUGUAY = &HE 


























Con 
Con 


UBLANG_SPANISH_PARAGUAY = &HF 
UBLANG_SPANISH_BOLIVIA = &H10 
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MAKELCID Macro 


Public Function MAKELCID (ByVal wLanguageId As Integer, ByVal wSortId As Integer) As 
Long 

















MAKELCID = wSortId * &H10000 + whanguageld 
End Function 





Description & Usage 


The MAKELCID macro creates a locale identifier. This identifier is based on two things: the locale's language and its string 
sort order. 


Return Value 


The macro returns the locale identifer that includes the specified language and string sort order. 


Visual Basic-Specific Issues 


None. 


Parameters 


wLanguageld 
The language identifier of the locale. Use the MAKELANGID macro to generate this value. 
wSortld 
One of the following flags specifying the string sort order for the locale: 
SORT_DEFAULT 
The default sort order. 
SORT_CHINESE_BIG5 
The Chinese BIGS sort order. 
SORT_CHINESE_UNICODE 
The Chinese Unicode sort order. 
SORT_JAPANESE_XJIS 
The Japanese XJIS sort order. 
SORT_JAPANESE_ UNICODE 
The Japanese Unicode order. 
SORT_KOREAN_KSC 
The Korean KSC sort order. 
SORT_KOREAN_UNICODE 
The Korean Unicode sort order. 
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Constant Definitions 


Const SORT DEFAULT = &HO 

Const SORT_CHINESE_ BIG5S = &H0O 
Const SORT _CHINESE UNICODE = &H1 
Const SORT_JAPANESE_XJIS = &HO 
Const SORT JAPANESE UNICODE = &H1 
Const SORT_KOREAN_KSC = &HO 
Const SORT KOREAN UNICODE = &H1 
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MAKEIPRANGE Macro 


Public Function MAKETPRANGE (ByVal low As Byte, ByVal high As Byte) As Long 
MAKEIPRANGE = low + CLng(high) * &H100 
End Function 





Description & Usage 


MAKEIPADDRESS packs a lower bound and an upper bound for an IP address field into a single 32-bit 
integer, suitable for use with the IPM_SETRANGE message. 


Return Value 


The macro returns the lower and upper bounds of the range packed into a single value. 


Visual Basic-Specific Issues 


None. 


Parameters 


low 

The lower bound of the range. 
high 

The upper bound of the range. 


Back to the Macro list. 
Back to the Reference section. 
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MAKEWORD Macro 


Public Function MAKEWORD (ByVal bLow As Byte, ByVal bHigh As Byte) As Integer 
MAKEWORD = Val("&H" & Right("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 











2)) 
End Function 


Description & Usage 


MAKEWORD creates a word by concatenating two individual bytes. 


Return Value 


The macro returns the 16-bit integer generated by the two bytes. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical computation, it is 
necessary to implement MAKEWORD this way in VB. Other methods to perform this task can fail for large inputs because 
VB interprets them as negative values, which causes an equivalent mathematical computation to return an unwanted value. 


Parameters 


bLow 

The low-order byte of the new 16-bit integer. 
bHigh 

The high-order byte of the new 16-bit integer. 


See Also 
HIBYTE, LOBYTE 


Back to the Macro list. 
Back to the Reference section. 
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MAKEPOINTS Macro 


Public Function MAKEPOINTS (ByVal lParam As Long) As POINT TYPE 





Description & Usage 


The MAKEPOINTS macro converts an (x,y) coordinate pair packed in a single 32-bit integer into the 
form of a POINT_TYPE structure. The macro separates the values stored in the low and high order 
words of the packed coordinates and places them into the structure. 


Return Value 


The macro returns a POINT_TYPE structure holding the unpacked coordinates. 


Visual Basic-Specific Issues 


None. 


Parameters 


lParam 
The packed coordinate pair to extract both coordinates from. 


See Also 
GET X LPARAM, GET _ Y LPARAM 


Back to the Macro list. 
Back to the Reference section. 
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SECOND_IPADDRESS Macro 


Public Function SECOND_IPADDRESS (ByVal ipAddress As Long) As Long 
SECOND_IPADDRESS = Val ("&H" & Mid(Right ("00000000" & Hex(ipAddress), 8), 3, 
































2)) 
End Function 


Description & Usage 


SECOND_IPADDRESS extracts the second field (field 1) from an IP address packed inside a 32-bit integer. The IP 
address must be in host byte order. 


Return Value 


The macro returns the value of the second field of the IP address. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical computation, it is 
necessary to implement SECOND_IPADDRESS this way in VB. Other methods to perform this task can fail for large 
inputs because VB interprets them as negative values, which causes an equivalent mathematical computation to return an 
unwanted value. 


Parameters 


ipAddress 
The IP address to get the second field of. The IP address must be packed into a 32-bit integer in host byte order. 


See Also 
FIRST IPADDRESS, FOURTH IPADDRESS, THIRD IPADDRESS 


Back to the Macro list. 
Back to the Reference section. 


Last Modified: October 29, 2000 
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THIRD_IPADDRESS Macro 


Public Function THIRD_IPADDRESS (ByVal ipAddress As Long) As Long 


THIRD_IPADDRESS = Val("&H" & Mid(Right ("O0000000" & Hex(ipAddress), 8), 5, 















































2)) 
End Function 


Description & Usage 


THIRD_IPADDRESS extracts the third field (field 2) from an IP address packed inside a 32-bit integer. The IP address 
must be in host byte order. 


Return Value 


The macro returns the value of the third field of the IP address. 


Visual Basic-Specific Issues 


Although it may seem unusual to use string operations for what would otherwise be a mathematical computation, it is 
necessary to implement THIRD_IPADDRESS this way in VB. Other methods to perform this task can fail for large 
inputs because VB interprets them as negative values, which causes an equivalent mathematical computation to return an 
unwanted value. 


Parameters 


ipAddress 
The IP address to get the third field of. The IP address must be packed into a 32-bit integer in host byte order. 


See Also 
FIRST IPADDRESS, FOURTH IPADDRESS, SECOND IPADDRESS 


Back to the Macro list. 
Back to the Reference section. 
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Windows API Reference: Other 
Information 


Last Update: January 21, 2001 


Below is an alphabetical list of other information related to some of the functions or structures in the 
Windows API. Most of the following information is used by a group of functions but is too large itself to 
be placed directly on the corresponding pages. Please keep in mind that this site does not encompass the 
entire API yet, so unfortunately may not find what you are looking for. To suggest any additions you 
would like to see made, please contact the author with your request. All pages added since the last update 
of this site are clearly marked with NEW. 


e Address Families 

e CSIDLs 

e Error Codes 

e Manufacturer IDs 

e MCI Command Strings 
e Product IDs 

e Virtual Key Codes 


e Window Classes & Styles 
e Winsock Error Codes 


Go back to the Reference section index. 
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Address Families 


Description & Usage 


The address families specify the different types of protocols that can be used with Winsock functions. 
The AF_INET family specifies IP-based protocols, which are the ones used on the Internet. However, 
Winsock supports a variety of other base network protocols you may use instead on other types of 
networks. 


AF_12844 

IEEE 1284.4 WG AF Protocol. 
AF_APPLETALK 

Appletalk protocol. 
AF_ATM 

Native ATM services protocol. 
AF_BAN 

Banyan protocol. 
AF_CCITT 

One of the CCITT protocols (such as X.25). 
AF_CHAOS 

One of the MIT CHAOS protocols. 
AF_CLUSTER 

Microsoft Wolfpack protocol. 
AF_DATAKIT 

One of the Datakit protocols. 
AF_DECnet 

DECnet protocol. 
AF_DLI 

Direct Data Link interface. 
AF_ECMA 

A European Computer Manufacturers protocol. 
AF_FIREFOX 

A FireFox protocol. 
AF_HYLINK 

NSC Hyperchannel protocol. 
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AF_IMPLINK 

Arpanet IMP address. 
AF_INET 

Internet or other inter-network address (such as UDP/IP or TCP/IP). 
AF_INET6 

Internet or other inter-network address using IPv6 addresses. 
AF_IPX 

One of the IPX protocols (such as IPX or SPX). 
AF_ISO 

One of the ISO protocols. 
AF_LAT 

LAT protocol. 
AF_NETBIOS 

NetBIOS protocol. 
AF_NS 

One of the Xerox NS protocols, including IPX. 
AF_OSI 

One of the ISO protocols. (Same as AF_ISO.) 
AF_PUP 

A PUP protocol address. 
AF_SNA 

IBM SNA protocol. 
AF_UNIX 

A Unix-type local-to-host pipe or portal. 
AF_UNKNOWNI1 

An unknown protocol. 
AF_VOICEVIEW 

VoiceView protocol. 


Constant Definitions 


Const AF_12844 = 25 

Const AF_APPLETALK = 16 
Const AF_ATM = 22 
Const AF_BAN = 21 
Const AF CCITT = 
Const AF CHAOS = 
Const AF_CLUSTER 2 
Const AF_DATAKIT = 9 
Const AF_DECnet = 12 
Const AF_DLI = 13 

Const AF_ECMA = 8 


| oar 


4 
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Const AF_FIREFOX = 19 
Const AF_HYLINK = 15 
Const AF_IMPLINK = 3 
Const AF_INET = 2 
Const AF_INET6 = 23 
Const AF_IPX = 6 

Const AF_ISO = 7 

Const AF_LAT = 14 
Const AF_NETBIOS = 17 
Const AF_NS = 6 

Const. AF_OSI = 7 

Const AF_PUP 4 

Const AF_SNA = 11 
Const AF_UNIX = 1 
Const AF_UNKNOWN1 = 20 
Const AF_VOICEVIEW = 18 


Used By 


gethostbyaddr, HOSTENT 


Back to the Reference section. 
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CSIDLs 


Description & Usage 


A CSIDL is a value identifying one of the special folders in the Windows shell. Special folders are 
folders which the shell uses for special purposes. For example, some special folders are the My 
Documents folder, the Recycle Bin, and the Internet Cache folder. These special folders can be either a 
physical path on a disk or a virtual folder. Windows NT, 2000: Many of the CSIDLs refer to folders 
specific to each user. The CSIDL_COMMON_* ones identify the analogous folders shared among all 
users. 


In some cases, a CSIDL can be combined with one of the following flags: 


CSIDL_FLAG_CREATE 

Windows 2000: If the folder the CSIDL refers to does not exist, create it. 
CSIDL_FLAG_DONT_VERIFY 

Windows 2000: Use the folder the CSIDL refers to even if it does not exist. 


Visual Basic-Specific Issues 


None. 


CSIDLs 


CSIDL_ADMINTOOLS 

Windows 2000: The Administration Tools folder. 
CSIDL_ALTSTARTUP 

The non-localized Startup folder. 
CSIDL_APPDATA 

The Application Data folder (used to store common program data). 
CSIDL_BITBUCKET 

The Recycle Bin on the desktop. 
CSIDL_COMMON_ADMINTOOLS 
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Windows 2000: The Administration Tools folder common to all users. 
CSIDL_COMMON_APPDATA 

Windows 2000: The Application Data folder (used to store common program data) common to 

all users. 
CSIDL_COMMON_ALTSTARTUP 

Windos NT, 2000: The non-localized Startup folder common to all users. 
CSIDL_COMMON_DESKTOPDIRECTORY 

Windows NT, 2000: The Desktop directory (used to store file objects on the Windows desktop) 

common to all users. 
CSIDL_COMMON_DOCUMENTS 

Windows NT, 2000: The Documents folder common to all users. 
CSIDL_COMMON_FAVORITES 

Windows NT, 2000: The Favorites folder common to all users. 
CSIDL_COMMON_PROGRAMS 

Windows NT, 2000: The Programs folder under the Start Menu common to all users. 
CSIDL_COMMON_STARTMENU 

Windows NT, 2000: The Start Menu folder common to all users. 
CSIDL_COMMON_STARTUP 

Windows NT, 2000: The Startup folder under Start Menu\Programs common to all users. 
CSIDL_COMMON_TEMPLATES 

Windows NT, 2000: The Templates folder common to all users. 
CSIDL_CONTROLS 

The Control Panel. 
CSIDL_COOKIES 

The folder used for Internet Explorer's cookie list. 
CSIDL_DESKTOP 

The Windows desktop. 
CSIDL_DESKTOPDIRECTORY 

The Desktop directory (used to hold file objects on the Windows desktop). 
CSIDL_DRIVES 

The My Computer folder. 
CSIDL_FAVORITES 

The Favorites folder (used primarily to store Internet Explorer's bookmarks). 
CSIDL_FONTS 

The Fonts directory (used to hold the fonts installed in Windows). 
CSIDL_HISTORY 

The folder used for Internet Explorer's history list. 
CSIDL_INTERNET 

The Internet (refering to the Internet Explorer icon on the desktop). 
CSIDL_INTERNET_CACHE 

The folder used for Internet Explorer's cache. 
CSIDL_LOCAL_APPDATA 

With Internet Explorer 5.0 or later: Local Application Data folder. 





http://216.26.168.92/vbapi/ref/other/csidls.html (2 of 5) [9/1/2002 6:15:01 PM] 


Windows API Guide: CSIDLs 


CSIDL_MYPICTURES 

With Internet Explorer 5.0 or later: The My Pictures folder. 
CSIDL_NETHOOD 

The Nethood directory (used to hold objects appearing in Network Neighborhood). 
CSIDL_NETWORK 

The Network Neighborhood folder. 
CSIDL_PERSONAL 

The My Documents folder. 
CSIDL_PRINTERS 

The Printers folder (under My Computer). 
CSIDL_PRINTHOOD 

The PrintHood directory (used to store printer links). 
CSIDL_PROFILE 

With Internet Explorer 5.0 or later: The user profile folder. 
CSIDL_PROGRAM_FILES 

With Internet Explorer 5.0 or later: The Program Files folder. 
CSIDL_PROGRAM_FILES_COMMON 

Windows NT, 2000: The Common folder under Program Files. 
CSIDL_PROGRAM_FILES_COMMONX86 

Windows 2000: The x86 Common folder under Program Files for RISC systems. 
CSIDL_PROGRAM_FILESX86 

Windows 2000: The x86 Program Files directory on RISC systems. 
CSIDL_PROGRAMS 

The Programs folder in the Start Menu. 
CSIDL_RECENT 

The Recent folder (used for the Documents list in the Start Menu). 
CSIDL_SENDTO 

The Send To folder (used to store Send To menu items). 
CSIDL_STARTMENU 

The Start Menu. 
CSIDL_STARTUP 

The Startup folder under Start Menu\Programs. 
CSIDL_SYSTEM 

With Internet Explorer 5.0 or later: The Windows System directory. 
CSIDL_SYSTEMX86 

Windows 2000: The x86 system directory on RISC systems. 
CSIDL_TEMPLATES 

The Templates folder (used to store document templates). 
CSIDL_WINDOWS 

With Internet Explorer 5.0 or later: The Windows directory. 


Constant Definitions 
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Const CSIDL_FLAG CREATE = &H8000 
Const CSIDL_FLAG DONT_VERIFY = &H4000 
Const CSIDL_ADMINTOOLS = &H30 

Const CSIDL_ALTSTARTUP = &HI1D 

Const CSIDL_APPDATA = &H1A 

Const CSIDL_BITBUCKET = &HA 

Const CSIDL_COMMON_ADMINTOOLS &H2F 
Const CSIDL_COMMON_ALTSTARTUP &H1D 
Const CSIDL_COMMON_APPDATA = &H23 
Const CSIDL_COMMON_DESKTOPDIRECTORY = &H19 
Const CSIDL_COMMON_DOCUMENTS = &H2E 
Const CSIDL_COMMON_FAVORITES = &HI1F 
Const CSIDL_COMMON_PROGRAMS = &H17 
Const CSIDL_COMMON_STARTMENU = &H16 
Const CSIDL_COMMON_STARTUP = &H18 
Const CSIDL_COMMON_TEMPLATES = &H2D 
Const CSIDL_CONTROLS = &H3 

Const CSIDL_COOKIES = &H21 

Const CSIDL_DESKTOP = &H0O 

Const CSIDL_DESKTOPDIRECTORY = &H10 
Const CSIDL_DRIVES = &H11 

Const CSIDL_FAVORITES = &H6 

Const CSIDL_FONTS = &H14 

Const CSIDL_HISTORY = &H22 

Const CSIDL_INTERNET = &H1 

Const CSIDL_INTERNET_CACHE = &H20 
Const CSIDL_LOCAL_APPDATA = &H1C 
Const CSIDL_MYPICTURES = &H27 

Const CSIDL_NETHOOD = &H13 

Const CSIDL_NETWORK = &H12 

Const CSIDL_PERSONAL &H5 

Const CSIDL_PRINTERS &H4 

Const CSIDL_PRINTHOOD = &H1B 

Const CSIDL_PROFILE = &H28 

Const CSIDL_PROGRAM_FILES = &H26 
Const CSIDL_PROGRAM_FILES_COMMON = &H2B 
Const CSIDL_PROGRAM_FILES_COMMONX86 = &H2C 
Const CSIDL_PROGRAM_FILESX86 = &H2A 
Const CSIDL_ PROGRAMS = &H2 

Const CSIDL RECENT &H8 

Const CSIDL_SENDTO &H9 

Const CSIDL_STARTMENU = &HB 

Const CSIDL_STARTUP = &H7 
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Const CSIDL_SYSTEM = &H25 
Const CSIDL_SYSTEMX86 = &H29 
Const CSIDL_TEMPLATES = &H15 
Const CSIDL_ WINDOWS = &H24 


Used By 


SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, SHGetSpecialFolderPath 


Go back to the Other Information listing. 
Go back to the Reference section index. 
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Glossary 


The following list defines many of the terms used in discussions about the Windows API and especially 
on this site. Please refer to this glossary whenever you are confused about the meaning of a term. A link 
to this glossary appears whenever one of the defined terms appears in the Windows API Guide. 


Atom 
An integer used to identify a string or integer stored in an atom table. Atoms can be stored in 
either an application's private atom table or the public atom table defined by the operating system. 
Back 

Brush 
A type of bitmap which is used to fill an area. Brushes are usually 8x8 pixel images, forming 
either a solid color or a pattern. Back 

Callback Function 
A function defined by the application which the Windows API will call. Callback functions are 
usually used whenever the program must process certain information itself at some time in the 
midst of the execution of an API function. In Visual Basic, all callback function must be declared 
Public and be defined in a module. Back 

Caret 
The flashing indicator which appears inside of text boxes. The caret identifies where the current 
position in the text box is. When text is typed, it (usually) appears inserted at the caret's position. 
Back 

Client Area 
The area of a window which contains the "actual" contents of the window. The client area does not 
include the title bar, the menu bar (if any), any toolbars or status bars, or the window's border. 
Coordinates measured within a window are usually taken relative to the client area. Back 

Common Dialog 
One of the dialog boxes built into the Windows API designed to allow the user to select 
something. The common dialog boxes include the Open File, Save File, Choose Color, Choose 
Font, Print, Print Setup, Find Text, and Find & Replace Text boxes. Back 

Current Point 
A point on a device also known as the last point referenced. Almost all drawing function ending in 
-To usually use the current point as the implied point to begin drawing from; they also set the 
current point to the end point of whatever was drawn. Other drawing functions completely ignore 
the current point. Back 
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Device 
An object which performs input or output operations (or both). Devices are used to communicate 
with the user and include such objects as the keyboard, mouse, and printers. Many windows are 
also considered to be devices. Devices are usually refered to using a device context. Back 

Device Context 
An object which both holds information about a device and provides a way to use the device. 
Device contexts refer to an internal data structure in Windows not accessible to applications; 
programs can only reference device context via a handle. Back 

Dword 
A portion of memory, usually a variable, which has a length of four bytes. The term dword is 
given to anything which is four bytes in length. Literally, a dword is a "double word." Back 

File Pointer 
A value identifying the current position in an open file. Any synchronous (not overlapped) read or 
write operations on the file begin at the byte position identified by the file pointer. Back 

Handle 
A four-byte integer used to identify a wide variety of objects. Handles refer to an internal data 
structure not accessible to Windows applications which contain information about an object. Back 

Hook Function 
A special type of callback function. Hook functions are used to process messages associated with 
an object such as a window or a dialog box. In general, hook functions are called to respond to 
some sort of message. Back 

Information Context 
A special type of device context. Unlike device contexts, an information context can only be used 
to read properties, settings, or other information about device. It cannot be used to actually do 





anything with the device. Back 

Item Identifier 
Identifies some object, usually a folder, used chiefly by the Windows shell. Programs rarely access 
these directly, but instead refer to them via a pointer. API functions almost always create these as 
necessary. Back 

Locale 
A collection of information specifying the type of language used to present certain kinds of 
information to the user. A locale consists of things such as the language, the date format, the 
currency format, the time format, etc. None of these settings actually affect the information itself, 
but how that information is displayed according to the user's preferences. Locales are typically 
referenced in the API using a numeric identifier. Back 

Logical 
When used to describe a graphics object (such as a font or brush), this means that the object 
described is an "ideal" object. Information about the logical object is used by the system to create 
a physical object which may not exactly match the logical one. However, only physical objects can 
actually be used. Back 

Message 
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A type of command sent to an object. Physically, a message is identified by a 32-bit integer. Most 
messages have two parameters associated with them. Most objects continually monitor for newly 
received messages and act on them. Back 

Mutex 
A synchronization object used for interprocess communication. A mutex can be owned by at most 
one thread at any one time, or it can be owned by none. A mutex is in a signaled state when it is 
unowned by a thread, and in a nonsignaled state when it is owned. Back 

Pen 
An object which is used to draw lines and curves. Pens define the style, size, and shape of a line or 
curve. Pens are usually refered to using a handle. Back 

Physical 
When used to describe a graphics object (such as a font or brush), this means that the object 
described is an actual object. Physical objects can be used to actually draw on devices. Back 

Pointer 
A four-byte integer used to identify a physical location in memory (a memory address). Often 
when using the API in Visual Basic, an implicit pointer to a variable can be used by passing it 
ByRef (except for Strings, which are always ByVal) as a parameter. Pointers can also be stored in 
Long-type variables. Back 

Region 
An object which identifies one or more areas of an area. Each component of a region can be of any 
shape, including (but not limited to) ellipses, rectangles, and other polygons. Regions can be 
combined in a variety of ways to create more complicated regions. Back 

Semaphore 
A synchronization object used for interprocess communication. A semaphore maintains a count 
between zero and a maximum value. A semaphore is in a signaled state when its count is positive, 
and in a nonsignaled state when its count is zero. Back 

Thread 
A path of execution in a program. Each application has at least one thread executing it, although it 
is possible to have more than one thread in the same instance of a program. Back 

Virtual Folder 
A folder which is treated like a folder by the Windows shell but does not correspond to a physical 
directory on any disk. For example, My Computer is a virtual folder which contains all the root 
drives, the Control Panel virtual folder, and other items. Virtual folders are rarely used by any non- 
shell functions. Back 

Window Class 
Defines attributes common to a group of windows. Windows which are created as a member of a 
certain window class inherit many properties of that class. The window class largely determines 
the look of its associated windows. Back 

Window Property 
An additional piece of information attached to a window. Window properties are referenced by a 
string identifier and hold a handle to the related piece of information. Window properties can be 
added, read, and removed from a window and do not by default have any bearing on the basic 
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operations of a window. Back 

Word 
A portion of memory, usually a variable, which has a length of two bytes. The term word is given 
to anything which is two bytes in length. Back 

Z-order 
An internal list identifying the overlapping of windows. Basically, the Z-order determines which 
windows lie on top of other windows. The top of the Z-order is the window which is on top of all 
other windows. Back 


Go back to the Reference section index. 
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Error Codes 


The error codes are values that identify different types of errors in the Windows API. Most functions do 
not report the error code directly; instead, they simply return a flag specifying if some error occured or 
not. The actual error code can usually be obtained by using the GetLastError function. 


The following list identifies various error codes defined in the Windows API. Your application may 
define its own error codes and use them with the error functions. However, make sure that bit 29 
(&H20000000) is set in any application-defined error code you define. Because no Windows API- 
defined error code has that bit set, using that bit assures that your error code will not conflict with an 
existing one. 


Error Codes 


NO_ERROR 

No Error / Success. 
ERROR_SUCCESS 

No Error / Success. 
ERROR_INVALID_FUNCTION 

Incorrect function. 
ERROR_FILE_NOT_FOUND 

The system cannot find the file specified. 
ERROR_PATH_NOT_FOUND 

The system cannot find the path specified. 
ERROR_TOO_MANY_OPEN_FILES 

The system cannot open the file because too many files are currently open. 
ERROR_ACCESS_DENIED 

Access denied. 
ERROR_INVALID_HANDLE 

The handle is invalid. 
ERROR_ARENA_TRASHED 

The storage control blocks were destroyed. 
ERROR_NOT_ENOUGH_MEMORY 

Insufficient memory is available to process the command. 
ERROR_INVALID_BLOCK 
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The storage control block address is invalid. 
ERROR_BAD_ENVIRONMENT 

The environment is incorrect. 
ERROR_BAD_FORMAT 

An attempt to load a program with an incorrect format was made. 
ERROR_INVALID_ACCESS 

The access code is invalid. 
ERROR_INVALID_DATA 

The data are invalid. 
ERROR_OUTOFMEMORY 

Insufficient memory is available to complete the operation. 
ERROR_INVALID_DRIVE 

The system cannot find the drive specified. 
ERROR_CURRENT_DIRECTORY 

The directory cannot be removed. 
ERROR_NOT_SAME_DEVICE 

The system cannot move the file to a different disk drive. 
ERROR_NO_MORE_FILES 

There are no more files. 
ERROR_WRITE_PROTECT 

The disk is write protected. 
ERROR_BAD_UNIT 

The system cannot find the device specified. 
ERROR_NOT_READY 

The device is not ready. 
ERROR_BAD_COMMAND 

The device does not recognize the command. 
ERROR_CRC 

Cyclic redundance check (CRC) data error. 
ERROR_BAD_LENGTH 

The length of the issued command is incorrect. 
ERROR_SEEK 

The drive cannot locate a specific area or track on the disk. 
ERROR_NOT_DOS_DISK 

The specified disk cannot be accessed. 
ERROR_SECTOR_NOT_FOUND 

The drive cannot find the sector requested. 
ERROR_OUT_OF_PAPER 

The printer is out of paper. 
ERROR_WRITE_FAULT 

The system cannot write to the specified device. 
ERROR_READ_FAULT 

The system cannot read from the specified device. 
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ERROR_GEN_FAILURE 

A device attached to the system is not functioning. 
ERROR_SHARING_VIOLATION 

The file cannot be accessed because it is in use by another process. 
ERROR_LOCK_VIOLATION 

The file cannot be accessed because another process has locked a portion of it. 
ERROR_WRONG_DISK 

The wrong disk is in the drive. 
ERROR_SHARING_BUFFER_EXCEEDED 

Too many files have been opened for sharing. 
ERROR_HANDLE_EOF 

The end of file (EOF) has been reached. 
ERROR_HANDLE_DISK_FULL 

The disk is full. 
ERROR_NOT_SUPPORTED 

The network request is not supported. 
ERROR_REM_NOT_LIST 

The remote computer is not available. 
ERROR_DUP_NAME 

A duplicate name exists on the network. 
ERROR_BAD_NETPATH 

The network path was not found. 
ERROR_NETWORK_BUSY 

The network is busy. 
ERROR_DEV_NOT_EXIST 

The specified network resource or device is not available. 
ERROR_TOO_MANY_CMDS 

The network BIOS command limit has been reached. 
ERROR_ADAP_HDW_ERR 

A network adapter hardware error has occured. 
ERROR_BAD_NET_RESP 

The specified server cannot perform the requested operation. 
ERROR_UNEXP_NET_ERROR 

An unexpected network error has occured. 
ERROR_BAD_REM_ADAP 

The remote adapter is incompatible. 
ERROR_PRINTQ_FULL 

The printer queue is full. 
ERROR_NO_SPOOL_SPACE 

No space to store the file waiting to be printed is available on the server. 
ERROR_PRINT_CANCELLED 

The file waiting to be printed was deleted. 
ERROR_NETNAME_DELETED 
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The specified network name is unavailable. 
ERROR_NETWORK_ACCESS_DENIED 

Network access is denied. 
ERROR_BAD_DEV_TYPE 

The network resource type is incorrect. 
ERROR_BAD_NET_NAME 

The network name cannot be found. 
ERROR_TOO_MANY_NAMES 

The name limit for the local computer network adapter card was exceeded. 
ERROR_TOO_MANY_SESS 

The network BIOS session limit was exceeded. 
ERROR_SHARING_PAUSED 

The remote server is paused or is in the process of beig started. 
ERROR_REQ_NOT_ACCEP 

The network request was not accepted. 
ERROR_REDIR_PAUSED 

The specified printer or disk device is paused. 
ERROR_FILE_EXISTS 

The file exists. 
ERROR_CANNOT_MAKE 

The directory or file cannot be created. 
ERROR_FAIL_I24 

Failure on Interrupt 24 (INT 24). 
ERROR_OUT_OF_STRUCTURES 

Storage to process the request is unavailable. 
ERROR_ALREADY_ASSIGNED 

The local device name is already in use. 
ERROR_INVALID_PASSWORD 

The specified network password is incorrect. 
ERROR_INVALID_PARAMETER 

The parameter is incorrect. 
ERROR_NET_WRITE_FAULT 

A write fault occured on the network. 
ERROR_NO_PROC_SLOTS 

The system cannot start another process at this time. 
ERROR_TOO_MANY_SEMAPHORES 

The system cannot create another semaphore. 
ERROR_EXCL_SEM_ALREADY_OWNED 

The exclusive semaphore is already owned by another process. 
ERROR_SEM_IS_SET 

The semaphore is set and cannot be closed. 
ERROR_TOO_MANY_SEM_REQUESTS 

The semaphore cannot be set again. 
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ERROR_INVALID_AT_INTERRUPT_TIME 

The system cannot request exclusive semaphores at interrupt time. 
ERROR_SEM_OWNER_DIED 

The previous ownership of this semaphore has ended. 
ERROR_SEM_USER_LIMIT 

The system has reached the semaphore user limit. 
ERROR_DISK_CHANGE 

The program stopped because the alternate disk was not inserted. 
ERROR_DRIVE_LOCKED 

The disk is in use or is locked by another process. 
ERROR_BROKEN_PIPE 

The pipe has been ended. 
ERROR_OPEN_FAILED 

The system cannot open the device or file specified. 
ERROR_BUFFER_OVERFLOW 

The file name is too long. 
ERROR_DISK_FULL 

There is insufficient space on the disk. 
ERROR_NO_MORE_SEARCH_HANDLES 

No more file search handles are available. 
ERROR_INVALID_TARGET_HANDLE 

The target file handle is incorrect. 
ERROR_INVALID_CATEGORY 

The IOCTL call made by the program is incorrect. 
ERROR_INVALID_VERIFY_SWITCH 

The verify-on-write parameter is incorrect. 
ERROR_BAD_DRIVER_LEVEL 

The system does not support the command requested. 
ERROR_CALL_NOT_IMPLEMENTED 

This function is only valid under Windows NT/2000. 
ERROR_SEM_TIMEOUT 

The semaphore timeout experiod has expired. 
ERROR_INSUFFIENT_BUFFER 

The data area passed to a system call is too small. 
ERROR_INVALID_NAME 

The syntax of the filename, directory name, or volume label is incorrect. 
ERROR_INVALID_LEVEL 

The system call level is incorrect. 
ERROR_NO_VOLUME_LABEL 

The disk has no volume label. 
ERROR_MOD_NOT_FOUND 

The specified module cannot be found. 
ERROR_PROC_NOT_FOUND 
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The specified procedure cannot be found. 
ERROR_WAIT_NO_CHILDREN 

There are no child processes to wait for. 
ERROR_CHILD_NOT_COMPLETE 

The program cannot run under Windows NT/2000. 
ERROR_DIRECT_ACCESS_HANDLE 

A file handle or open disk partition was attempted to be used for an operation other than raw disk 

T/O. 
ERROR_NEGATIVE_SEEK 

An attempt was made to move a file pointer before the beginning of the file. 
ERROR_SEEK_ON_DEVICE 

The file pointer cannot be set on the specified device or file. 
ERROR_IS_JOIN_TARGET 

A JOIN or SUBST command cannot be used for a drive that contains previously joined drives. 
ERROR_IS_JOINED 

An attempt was made to use a JOIN or SUBST command on a drive that has already been joined. 
ERROR_IS_SUBSTED 

An attempt was made to use a JOIN or SUBST command on a drive that has already been 

substituted. 
ERROR_NOT_JOINED 

The system tried to delete the JOIN of a drive that is not joined. 
ERROR_NOT_SUBSTED 

The system tried to delete the SUBST of a drive that is not substituted. 
ERROR_JOIN_TO_JOIN 

The system tried to JOIN a drive to a directory on a joined drive. 
ERROR_SUBST_TO_SUBST 

The system tried to SUBST a drive to a directory on a substituted drive. 
ERROR_JOIN_TO_SUBST 

The system tried to JOIN a drive to a directory on a substituted drive. 
ERROR_SUBST_TO_JOIN 

The system tried to SUBST a drive to a directory on a joined drive. 
ERROR_BUSY_DRIVE 

The system cannot perform a JOIN or SUBST at this time. 
ERROR_SAME_DRIVE 

The system cannot JOIN or SUBST a drive to or for a directory on the same drive. 
ERROR_DIR_NOT_ROOT 

The directory is not a subdirectory of the root directory. 
ERROR_DIR_NOT_EMPTY 

The directory is not empty. 
ERROR_IS_SUBST_PATH 

The path specified is being used in a SUBST. 
ERROR_IS_JOIN_PATH 

The path specified is being used in a JOIN. 
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ERROR_PATH_BUSY 

The path specified cannot be used at this time. 
ERROR_IS_SUBST_TARGET 

An attempt was made to JOIN or SUBST a drive for which a directory on the drive is the target of 

a previous SUBST. 
ERROR_SYSTEM_TRACE 

System trace information was not specified in CONFIG.SYS, or tracing is not allowed. 
ERROR_INVALID_EVENT_COUNT 

The number of specified semaphore events is incorrect. 
ERROR_TOO_MANY_MUXWAITERS 

DosMuxSemWait did not execute because too many semaphores are already set. 
ERROR_INVALID_LIST_FORMAT 

The DosMuxSemWait list is incorrect. 
ERROR_LABEL_TOO_LONG 

The volume label specified is too long and was truncated to 11 characters. 
ERROR_TOO_MANY_TCBS 

The system cannot create another thread. 
ERROR_SIGNAL_REFUSED 

The recipient process has refused the signal. 
ERROR_DISCARDED 

The segment is already discarded and cannot be locked. 
ERROR_NOT_LOCKED 

The segment is already unlocked. 
ERROR_BAD_THREADID_ADDR 

The address for the thread ID is incorrect. 
ERROR_BAD_ARGUMENTS 

The argument string is incorrect. 
ERROR_BAD_PATHNAME 

The specified path is invalid. 
ERROR_SIGNAL_PENDING 

A signal is already pending. 
ERROR_MAX_THRDS_REACHED 

No more threads can be created in the system. 
ERROR_LOCK_FAILED 

The system was unable to lock a region of a file. 
ERROR_BUSY 

The requested resource is in use. 
ERROR_CANCEL_VIOLATION 

A lock request was not outstanding for the supplied cancel region. 
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED 

The file system does not support atomic changes to the lock type. 
ERROR_INVALID_SEGMENT_NUMBER 

The system detected an incorrect segment number. 
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ERROR_INVALID_ORDINAL 

The system cannot run something because of an invalid ordinal. 
ERROR_ALREADY_EXISTS 

The system cannot create a file when it already exists. 
ERROR_INVALID_FLAG_NUMBER 

An incorrect flag was passed. 
ERROR_SEM_NOT_FOUND 

The specified system semaphore name was not found. 
ERROR_INVALID_STARTING_CODESEG 

The system cannot run something because of an invalid starting code segment. 
ERROR_INVALID_STACKSEG 

The system cannot run something because of an invalid stack segment. 
ERROR_INVALID_MODULETYPE 

The system cannot run something because of an invalid module type. 
ERROR_INVALID_EXE_SIGNATURE 

The system cannot run something because it cannot run under Windows NT/2000. 
ERROR_EXE_MARKED_INVALID 

The system cannot run something because the EXE was marked as invalid. 
ERROR_BAD_EXE_FORMAT 

The system cannot run something because it is an invalid Windows NT/2000 application. 
ERROR_ITERATED_DATA_EXCEEDS_64K 

The system cannot run something because the iterated data exceed 64KB. 
ERROR_INVALID_MINALLOCSIZE 

The system cannot run something because of an invalid minimum allocation size. 
ERROR_DYNLINK_FROM_INVALID_RING 

The system cannot run something because of a dynalink from an invalid ring. 
ERROR_IOPL_NOT_ENABLED 

The system is not presently configured to run this application. 
ERROR_INVALID_SEGDPL 

The system cannot run something because of an invalid segment DPL. 
ERROR_AUTODATASEG_EXCEEDS_64KB 

The system cannot run something because the automatic data segment exceeds 64K. 
ERROR_RING2SEG_MUST_BE_MOVABLE 

The code segment cannot be greater than or equal to 64KB. 
ERROR_RELOC_CHAIN_XEEDS_SEGLIM 

The system cannot run something because the reallocation chain exceeds the segment limit. 
ERROR_INFLOOP_IN_RELOC_CHAIN 

The system cannot run something because of an infinite loop in the reallocation chain. 
ERROR_ENVVAR_NOT_FOUND 

The system could not find the specified environment variable. 
ERROR_NO_SIGNAL_SENT 

No process in the command subtree has a signal handler. 
ERROR_FILENAME_EXCED_RANGE 
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The filename or extension is too long. 
ERROR_RING2_STACK_IN_USE 

The ring 2 stack is busy. 
ERROR_META_EXPANSION_TOO_LONG 

The global filename characters (or ?) are entered incorrectly, or too amny global filename 

characters are specified. 
ERROR_INVALID_SIGNAL_NUMBER 

The signal being posted is incorrect. 
ERROR_THREAD_1_INACTIVE 

The signal handler cannot be set. 
ERROR_LOCKED 

The segment is locked and cannot be reallocated. 
ERROR_TOO_MANY_MODULES 

Too many dynamic link modules are attacked to this program or module. 
ERROR_NESTING_NOT_ALLOWED 

Nesting of calls to LoadModule is not allowed. 
ERROR_BAD_PIPE 

The pipe state is invalid. 
ERROR_PIPE_BUSY 

All pipe instances are busy. 
ERROR_NO_DATA 

The pipe is being closed. 
ERROR_PIPE_NOT_CONNECTED 

No process exists on the other end of the pipe. 
ERROR_MORE_DATA 

More data is available. 
ERROR_VC_DISCONNECTED 

The session was cancelled. 
ERROR_INVALID_EA_NAME 

The specified extended attribute name was invalid. 
ERROR_EA_LIST_INCONSISTENT 

The extended attributes are inconsistent. 
ERROR_NO_MORE_ITEMS 

No more data is available. 
ERROR_CANNOT_COPY 

The Copy API cannot be used. 
ERROR_DIRECTORY 

The directory name is invalid. 
ERROR_EAS_DIDNT_FIT 

The extended attributes did not fit into the buffer. 
ERROR_EA_FILE_CORRUPT 

The extended attribute file on the mounted file system is corrupt. 
ERROR_EA_TABLE_FULL 
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The extended attribute table file is full. 
ERROR_INVALID_EA_HANDLE 

The specified extended attribute handle is invalid. 
ERROR_EAS_NOT_SUPPORTED 

The mounted file system does not support extended attributes. 
ERROR_NOT_OWNER 

The system attempted to release a mutex not owned by the caller. 
ERROR_TOO_MANY_POSTS 

Too many posts were made to a semaphore. 
ERROR_MR_MID_NOT_FOUND 

The system cannot find the message for the specified message number in the proper message file. 
ERROR_INVALID_ADDRESS 

The system attempted to access an invalid address. 
ERROR_ARITHMETIC_OVERFLOW 

An arithmetic overflow (result > 32 bits) occured. 
ERROR_PIPE_CONNECTED 

A process already exists on the other end of the pipe. 
ERROR_PIPE_LISTENING 

The system is waiting for a process to open on the other end of the pipe. 
ERROR_EA_ACCESS_DENTED 

Access to the extended attribute was denied. 
ERROR_OPERATED_ABORTED 

The I/O operation has been aborted because of either a thread exit or an application request. 
ERROR_IO_INCOMPLETE 

The overlapped I/O event is not in a signalled state. 
ERROR_IO_PENDING 

The overlapped I/O operation is in progress. 
ERROR_NOACCESS 

An invalid access to a memory location was attempted. 
ERROR_SWAPERROR 

An error performing an inpage operation occured. 
ERROR_STACK_OVERFLOW 

The stack overflowed because recursion was too deep. 
ERROR_INVALID_MESSAGE 

The window cannot act on the sent message. 
ERROR_CAN_NOT_COMPLETE 

The function cannot be completed. 
ERROR_INVALID_FLAGS 

Invalid flags were used. 
ERROR_UNRECOGNIZED_VOLUME 

The disk volume does not contain a recognized file system. 
ERROR_FILE_INVALID 

The disk volume for a file has been altered such that the opened file is no longer valid. 
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ERROR_FULLSCREEN_MODE 

The requested operation cannot be performed in full-screen mode. 
ERROR_NO_TOKEN 

An attempt to reference a nonexistent token was made. 
ERROR_BADDB 

The registry database is corrupt. 
ERROR_BADKEY 

The registry key is invalid. 
ERROR_CANTOPEN 

The registry key could not be opened. 
ERROR_CANTREAD 

The registry key could not be read from. 
ERROR_CANTWRITE 

The registry key could not be written to. 
ERROR_REGISTRY_RECOVERED 

One of the registry database files was successfully recovered. 
ERROR_REGISTRY_CORRUPT 

The registry is corrupt. The cause could be a corrupted registry database file, a corrupted image in 

system memory, or a failed attempt to recover the registry because of a missing or corrupted log. 
ERROR_REGISTRY_IO_FAILED 

An I/O operation initiated by the registry failed unrecoverably. 
ERROR_NOT_REGISTR Y_FILE 

The system tried to load or restore a file into the registry, but that file is not in the proper file 

format. 
ERROR_KEY_DELETED 

An illegal operation was attempted on a registry key marked for deletion. 
ERROR_NO_LOG_SPACE 

The system could not allocate the required space in a registry log. 
ERROR_KEY_HAS_CHILDREN 

A symbolic link in a registry key that already has subkeys or values cannot be created. 
ERROR_CHILD_MUST_BE_VOLATILE 

A stable subkey cannot be created under a volatile parent key. 
ERROR_NOTIFY_ENUM_DIR 

Because a notify change request is being completed and the information is not being returned in 

the caller's buffer, the caller must now enumerate the files to find the changes. 
ERROR_DEPENDENT_SERVICES_RUNNING 

A stop control has been sent to a service which other running services are dependent on. 
ERROR_INVALID_SERVICE_CONTROL 

The requested control is not valid for this service. 
ERROR_SERVICE_REQUEST_TIMEOUT 

The service did not respond to the start or control request within the timeout period. 
ERROR_SERVICE_NO_THREAD 

A thread could not be created for the service. 
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ERROR_SERVICE_DATABASE_LOCKED 

The service database is locked. 
ERROR_SERVICE_ALREADY_RUNNING 

An instance of the service is already running. 
ERROR_INVALID_SERVICE_ACCOUNT 

The account name for the service is invalid or nonexistent. 
ERROR_SERVICE_DISABLED 

The specified service is disabled and cannot be started. 
ERROR_CIRCULAR_DEPENDENCY 

A circular service dependency was specified. 
ERROR_SERVICE_DOES_NOT_EXIST 

The specified service does not exist. 
ERROR_SERVICE_CANNOT_ACCEPT_CTRL 

The service cannot accept control messages at this time. 
ERROR_SERVICE_NOT_ACTIVE 

The service has not been started. 
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT 

The service process could not connect to the service controller. 
ERROR_EXCEPTION_IN_SERVICE 

An exception occured in the service when handling the control request. 
ERROR_DATABASE_DOES_NOT_EXIST 

The specified database does not exist. 
ERROR_SERVICE_SPECIFIC_ERROR 

The service has returned a service-specific error code. 
ERROR_PROCESS_ABORTED 

The process terminated unexpectedly. 
ERROR_SERVICE_DEPENDENCY_FAIL 

The dependency service or group failed to start. 
ERROR_SERVICE_LOGON_FAILED 

The service did not start due to a logon failure. 
ERROR_SERVICE_START_HANG 

After starting, the service hung in a start-pending state. 
ERROR_INVALID_SERVICE_LOCK 

The specified service database lock is invalid. 
ERROR_SERVICE_MARKED_FOR_DELETE 

The specified service has been marked for deletion. 
ERROR_SERVICE_EXISTS 

The specified service already exists. 
ERROR_ALREADY_RUNNING_LKG 

The system is currently running with the last-known-good configuration. 
ERROR_SERVICE_DEPENDENCY_DELETED 

The dependency service does not exist or has been marked for deletion. 
ERROR_BOOT_ALREADY_ACCEPTED 


http://216.26.168.92/vbapi/ref/other/errorcodes.html (12 of 21) [9/1/2002 6:15:59 PM] 


Windows API Guide: Error Codes 


The current boot has already been accepted for use as the last-known-good control set. 
ERROR_SERVICE_NEVER_STARTED 

No attempts to start the service have been made. 
ERROR_DUPLICATE_SERVICE_NAME 

The name is already in use either as a service name or as a service display name. 
ERROR_END_OF_MEDIA 

The physical end of the tape has been reached. 
ERROR_FILEMARK_DETECTED 

A tape access reached a filemark. 
ERROR_BEGINNING_OF_MEDIA 

The beginning of the tape or partition was encountered. 
ERROR_SETMARK_DETECTED 

A tape access reached the end of a set of files. 
ERROR_NO_DATA_DETECTED 

No more data is on the tape. 
ERROR_PARTITION_FAILURE 

The tape could not be partitioned. 
ERROR_INVALID_BLOCK_LENGTH 

When accessing a new tape of a multivolume partition, the current blocksize is incorrect. 
ERROR_DEVICE_NOT_PARTITIONED 

The tape partition information could not be found. 
ERROR_UNABLE_TO_LOCK_MEDIA 

The system was unable to lock the media eject mechanism. 
ERROR_UNABLE_TO_UNLOAD_MEDIA 

The system was unable to unload the media. 
ERROR_MEDIA_CHANGED 

The media in the drive may have changed. 
ERROR_BUS_RESET 

The I/O bus was reset. 
ERROR_NO_MEDIA_IN_DRIVE 

There is no media in the drive. 
ERROR_NO_UNICODE_TRANSLATION 

No mapping for the Unicode character exists in the target multi-byte code page. 
ERROR_DLL_INIT_FAILED 

A dynamic link library initialization routine failed. 
ERROR_SHUTDOWN_IN_PROGRESS 

A system shutdown is in progress. 
ERROR_NO_SHUTDOWN_IN_PROGRESS 

The system shutdown could not be aborted because no shutdown is in progress. 
ERROR_IO_DEVICE 

The request could not be performed because of an device I/O error. 
ERROR_SERIAL_NO_DEVICE 

No serial device was successfully initialized; the serial driver will therefore unload. 
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ERROR_IRQ_BUSY 

The system was unable to open a device sharing an interrupt request (IRQ) with other device(s) 

because at least one of those devices is already opened. 
ERROR_MORE_WRITES 

A serial I/O operation was completed by another write to the serial port. 
ERROR_COUNTER_TIMEOUT 

A serial I/O operation completed because the time-out period expired. 
ERROR_FLOPPY_ID_MARK_NOT_FOUND 

No ID address mark was found on the floppy disk. 
ERROR_FLOPPY_WRONG_CYLINDER 

A mismatch exists between the floppy disk sector ID field and the floppy disk controller track 

address. 
ERROR_FLOPPY_UNKNOWN_ERROR 

The floppy disk controller reported an unrecognized error. 
ERROR_FLOPPY_BAD_REGISTERS 

The floppy disk controller returned inconsistent results in its registers. 
ERROR_DISK_RECALIBRATE_FAILED 

While accessing a hard disk, a recalibrate operation failed, even after retries. 
ERROR_DISK_OPERATION_FAILED 

While accessing a hard disk, a disk operation failed, even after retries. 
ERROR_DISK_RESET_FAILED 

While accessing a hard disk, a disk controller reset was needed, but even that failed. 
ERROR_EOM_OVERFLOW 

An EOM overflow occured. 
ERROR_NOT_ENOUGH_SERVER_MEMORY 

Not enough server storage is available to process this command. 
ERROR_POSSIBLE_DEADLOCK 

A potential deadlock condition has been detected. 
ERROR_MAPPED_ALIGNMENT 

The base address or the file offset specified does not have the proper alignment. 


Constant Definitions 


Const NO_ERROR = 0 

Const ERROR SUCCESS. = 0 
Const ERROR_INVALID_ FUNCTION 
Const ERROR_FILE NOT FOUND = 
Const ERROR_PATH_NOT_FOUND = 
Const ERROR_TOO_MANY _OPEN_FILES = 4 
Const ERROR_ACCESS_DENIED = 5 

Const ERROR_INVALID_ HANDLE = 6 
Const ERROR_ARENA TRASHED = 7 


wh il 
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Const ERROR_NOT_ENOUGH_MEMORY = 8 
Const ERROR_INVALID_ BLOCK = 9 
Const ERROR_BAD ENVIRONMENT = 10 
Const ERROR_BAD FORMAT = 11 

Const ERROR_INVALID_ACCESS = 12 
Const ERROR_INVALID_DATA = 13 
Const ERROR_OUTOFMEMORY = 14 
Const ERROR_INVALID DRIVE = 15 
Const ERROR_CURRENT_DIRECTORY = 16 
Const ERROR_NOT_SAME DEVICE = 17 
Const ERROR_NO_MORE_FILES = 18 
Const ERROR_WRITE PROTECT = 19 
Const ERROR_BAD UNIT = 20 

Const ERROR_NOT_READY = 21 

Const ERROR_BAD COMMAND = 22 
Const ERROR_CRC = 23 

Const ERROR_BAD_LENGTH = 24 

Const ERROR_SEEK = 25 

Const ERROR_NOT_DOS_DISK = 26 
Const ERROR_SECTOR_NOT_FOUND = 27 
Const ERROR_OUT_OF_PAPER = 28 
Const ERROR_WRITE_FAULT = 29 
Const ERROR_READ_FAULT = 30 

Const ERROR_GEN_FAILURE = 31 
Const ERROR_SHARING_VIOLATION = 32 
Const ERROR_LOCK_VIOLATION = 33 
Const ERROR_WRONG_DISK = 34 

Const ERROR_SHARING_BUFFER_EXCEEDED = 36 
Const ERROR_HANDLE_EOF = 38 

Const ERROR_HANDLE_DISK_FULL = 39 
Const ERROR_NOT_SUPPORTED = 50 
Const ERROR_REM_NOT_LIST = 51 
Const ERROR_DUP_NAME = 52 

Const ERROR_BAD_NETPATH = 53 
Const ERROR_NETWORK_BUSY = 54 
Const ERROR_DEV_NOT_EXIST = 55 
Const ERROR_TOO_MANY_CMDS = 56 
Const ERROR_ADAP_HDW_ERR = 57 
Const ERROR_BAD_NET_RESP = 58 
Const ERROR_UNEXP_NET_ERR = 59 
Const ERROR_BAD_REM_ADAP = 60 
Const ERROR_PRINTQ_FULL = 61 
Const ERROR_NO_SPOOL_SPACE = 62 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


ERROR_PRINT_CANCELLED = 63 
ERROR_NETNAME DELETED 64 
EFRROR_NETWORK_ACCESS_DENIED = 
ERROR_BAD_DEV_TYPE = 66 
ERROR_BAD_NET_NAME = 67 
EFRROR_TOO_MANY_NAMES = 
FRROR_TOO_MANY_SESS = 
EFRROR_SHARING_PAUSED = 
ERROR. REO NOT ACCEP = 
FRROR_REDIR_PAUSED = 
ERROR.FILE EXISTS = 
ERROR_CANNOT_MAKE = 
ERROR_FAIL_I24 = 83 
ERBROR-OUTWOF- STRUCTURES: = 
ERROR_ALREADY_ASSIGNED = 
EFRROR_INVALID_PASSWORD = 
FRROR_INVALID_PARAMETER = 
ERROR_NET_WRITE_FAULT = 88 
ERROR_NO_PROC_SLOTS = 89 
ERROR_TOO_MANY_SEMAPHORES = 100 
FRROR_EXCL_SEM_ALREADY_OWNED = 
ERROR_SEM_IS_SET = 102 
ERROR_TOO_MANY_SEM_ REQUESTS = 103 
ERROR. INVALID UAT: LNTERRUP TO TIME = 
ERROR_SEM_OWNER_DIED = 105 
ERROR_SEM_USER_LIMIT = 106 
ERROR_DISK_CHANGE = 107 
ERROR_DRIVE_LOCKED = 108 
ERROR_BROKEN_PIPE = 109 
EFRROR_OPEN_FATILED 110 
ERROR_BUFFER_OVERFLOW = 
ERROR_DISK_FULL = 112 
ERROR_NO_MORE_SEARCH_HANDLES = 
ERROR_INVALID_TARGET_HANDLE = 
ERROR_INVALID_CATEGORY = 117 
ERROR_INVALID_VERIFY_SWITCH = 
ERROR_BAD_DRIVER_LEVEL = 119 
ERROR_CALL_NOT_IMPLEMENTED = 
ERROR_SEM_TIMEOUT = 121 
ERROR_INSUFFICIENT_BUFFER = 
ERROR_INVALID_NAME = 123 
ERROR_INVALID_LEVEL = 124 
ERROR_NO_VOLUME_LABEL = 125 


65 


68 
69 
70 
71 
72 
80 
82 





84 
85 
86 

87 


101 


Tla. 


113 
114 


118 


120 


122 
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Const ERROR_MOD_NOT_FOUND = 126 

Const ERROR_PROC_NOT_FOUND = 127 
Const ERROR_WAIT_NO_ CHILDREN = 128 
Const ERROR_CHILD_NOT_COMPLETE = 129 
Const ERROR_DIRECT_ACCESS_HANDLE = 130 
Const ERROR_NEGATIVE_ SEEK = 131 

Const ERROR_SEKEK_ON_DEVICE = 132 
Const ERROR_IS_JOIN_TARGET 133 
Const ERROR_IS_JOINED = 134 

Const ERROR_IS_SUBSTED IESS) 

Const ERROR_NOT_JOINED = 136 

Const ERROR_NOT_SUBSTED = 137 

Const ERROR_JOIN_TO_JOIN = 138 

Const ERROR_SUBST_TO_SUBST = 139 
Const ERROR_JOIN_TO_SUBST = 140 

Const ERROR_SUBST_TO_JOIN = 141 

Const ERROR_BUSY_DRIVE = 142 

Const ERROR_SAME_DRIVE = 143 

Const ERROR_DIR_NOT_ROOT = 144 

Const ERROR_DIR_NOT_EMPTY = 145 

Const ERROR_IS_SUBST_PATH = 146 

Const ERROR_IS_JOIN_PATH = 147 

Const ERROR_PATH_BUSY = 148 

Const ERROR_IS_SUBST_TARGET = 149 
Const ERROR_SYSTEM_TRACE = 150 

Const ERROR_INVALID_EVENT_COUNT = 151 
Const ERROR_TOO_MANY_MUXWAITERS = 152 
Const ERROR_INVALID_LIST_FORMAT = 153 
Const ERROR_LABEL TOO_LONG = 154 
Const ERROR_TOO_MANY_TCBS = 155 

Const ERROR_SIGNAL REFUSED = 156 
Const ERROR_DISCARDED = 157 

Const ERROR_NOT_LOCKED = 158 

Const ERROR_BAD THREADID_ADDR = 159 
Const ERROR_BAD ARGUMENTS = 160 

Const ERROR_BAD PATHNAME = 161 

Const ERROR_SIGNAL PENDING = 162 
Const ERROR_MAX THRDS_ REACHED = 164 
Const ERROR_LOCK_FAILED = 167 

Const ERROR_BUSY = 170 

Const ERROR_CANCEL VIOLATION = 173 
Const ERROR_ATOMIC_LOCKS_NOT_SUPPORTED = 174 
Const ERROR_INVALID_SEGMENT_NUMBER = 180 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


EFRROR_INVALID_ORDINAL 182 
EFRROR_ALREADY_EXISTS T83 
ERROR_INVALID_FLAG_NUMBER 

ERROR_SEM_NOT_FOUND 1:37 

ERROR_INVALID_STARTING_CODE 
ERROR_INVALID_STACKSEG aes 
EFRROR_INVALID_MODULETYPE = 

EFRROR_INVALID_EXE_SIGNATURE 
FRROR_EXE_MARKED_INVALID 
EFRROR_BAD_EXE_FORMAT 193 











ERROR_ITERATED_DATA_EXCEEDS_64k 


ERROR_INVALID_MINALLOCSIZE 


ERROR_DYNLINK_FROM_INVALID_ 


ERROR_IOPL_NOT_ENABLED 19 
FRROR_INVALID_SEGDPL 198 

ERROR_AUTODATASEG _EXCEEDS_6 
ERROR_RING2SEG_MUST_BE_MOVA 
FRROR_RELOC_CHAIN_XEEDS_SEG 


FRROR_INFLOOP_IN_RELOC_CHAIN 


FRROR_ENVVAR_NOT_FOUND 20 
EFRROR_NO_SIGNAL_SENT 205 
EFRROR_FILENAME EXCED_RANGE 
ERROR_RING2_STACK_IN_USE 





EFRROR_META_EXPANSION_TOO_LONG 


EFRROR_INVALID_SIGNAL_NUMBER 
EKRROR_THREAD_1_INACTIVE 2 
ERROR_LOCKED 212 
ERROR_TOO_MANY_MODULES 
ERROR_NESTING_NOT_ALLOWED 
ERROR_BAD_PIPE 230 
ERROR_PIPE_BUSY ZO 
ERROR_NO_DATA 232 
ERROR_PIPE_NOT_CONNECTED 
ERROR_MORE_DATA 234 
ERROR_VC_DISCONNECTED 240 
ERROR_INVALID_EA_NAME = 254 
ERROR_EA_LIST_INCONSISTENT 
ERROR_NO_MORE_ITEMS 259 
ERROR_CANNOT_COPY 266 
ERROR_DIRECTORY 267 
ERROR_EAS_DIDNT_FIT 
ERROR_EA_FILE_CORRUPT 
ERROR_EA_TABLE_FULL 


21 


245 
276 
2 


186 
SEG = 188 
9 
190 

= 191 
1:92 

= 194 

= 195 
RING = 196 
7 
4k = 199 
BLE = 200 
LIM = 201 

= 202 
3 
= 206 
207 

= 208 

= 209 
10 
4 

215 
233 
= 255 


http://216.26.168.92/vbapi/ref/other/errorcodes.html (18 of 21) [9/1/2002 6:15:59 PM] 


Windows API Guide: Error Codes 


Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


ERROR_INVALID_EA HANDLE = 278 


ERROR_EAS_NOT_SUPPORTED = 282 
ERROR_NOT_OWNER = 288 
ERROR_TOO_MANY_POSTS = 298 
ERROR_MR_MID_NOT_FOUND = 317 
ERROR_INVALID_ADDRESS = 487 
ERROR_ARITHMETIC_OVERFLOW = 534 


BRROR_PIPE_CONNECTED = 535 
ERROR_PIPE_LISTENING = 536 








ERROR_EA_ACCESS_DENIED = 994 
ERROR_OPERATION_ABORTED = 995 
ERROR_IO_INCOMPLETE = 996 
ERROR_IO_PENDING = 997 
ERROR_NOACCESS = 998 

ERROR_SWAPERROR = 999 
ERROR_STACK_OVERFLOW = 1001 
ERROR_INVALID_MESSAGE = 1002 
ERROR_CAN_NOT_COMPLETE = 1003 
ERROR_INVALID_FLAGS = 1004 
ERROR_UNRECOGNIZED_VOLUME = 1005 
ERROR_FILE_INVALID = 1006 
ERROR_FULLSCREEN_MODE = 1007 
ERROR_NO_TOKEN = 1008 

ERROR_BADDB = 1009 

ERROR_BADKEY = 1010 

ERROR_CANTOPEN = 1011 

ERROR_CANTREAD = 1012 
ERROR_CANTWRITE = 1013 
ERROR_REGISTRY_RECOVERED = 1014 
ERROR_REGISTRY_CORRUPT = 1015 
ERROR_REGISTRY_IO_FAILED = 1016 
ERROR_NOT_REGISTRY_FILE = 1017 
ERROR_KEY_DELETED = 1018 
ERROR_NO_LOG_SPACE = 1019 
ERROR_KEY_HAS_ CHILDREN = 1020 
ERROR_CHILD_MUST_BE_ VOLATILE = 1021 
ERROR_NOTIFY_ENUM_DIR = 1022 
ERROR_DEPENDENT_SERVICES_RUNNING = 1051 
ERROR_INVALID_SERVICE_CONTROL = 1052 
ERROR_SERVICE_REQUEST_TIMEOUT = 1053 
ERROR_SERVICE_NO_THREAD = 1054 
ERROR_SERVICE_DATABASE_ LOCKED = 1055 
ERROR_SERVICE_ALREADY_RUNNING = 1056 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


ERROR_INVALID_SERVICE_ACCOUNT = 1057 
ERROR_SERVICE_DISABLED = 1058 
ERROR_CIRCULAR_DEPENDENCY = 1059 
ERROR_SERVICE_DOES_NOT_EXIST = 1060 
ERROR_SERVICE_CANNOT_ACCEPT_CTRL = 1061 
ERROR_SERVICE_NOT_ACTIVE = 1062 
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT = 1063 
ERROR_EXCEPTION_IN_SERVICE = 1064 
ERROR_DATABASE_DOES_NOT_EXIST = 1065 
ERROR_SERVICE_SPECIFIC_ERROR = 1066 
ERROR_PROCESS_ABORTED = 1067 
ERROR_SERVICE_DEPENDENCY_FAIL = 1068 
ERROR_SERVICE_LOGON_FAILED = 1069 
ERROR_SERVICE_START_HANG = 1070 
ERROR_INVALID_SERVICE_LOCK = 1071 
ERROR_SERVICE_MARKED_FOR_DELETE = 1072 
ERROR_SERVICE_EXISTS = 1073 
ERROR_ALREADY_RUNNING_LKG = 1074 
ERROR_SERVICE_DEPENDENCY_DELETED = 1075 
ERROR_BOOT_ALREADY_ACCEPTED = 1076 
ERROR_SERVICE_NEVER_STARTED = 1077 
ERROR_DUPLICATE_SERVICE_NAME = 1078 
ERROR_END_OF_MEDIA = 1100 
ERROR_FILEMARK_DETECTED = 1101 
ERROR_BEGINNING_OF_MEDIA = 1102 
ERROR_SETMARK_ DETECTED = 1103 
ERROR_NO_DATA_DETECTED = 1104 
ERROR_PARTITION_FAILURE = 1105 
ERROR_INVALID_BLOCK_LENGTH = 1106 
ERROR DEVICE NOT. PARTITIONED 1107 
ERROR_UNABLE_TO_LOCK_MEDIA = 1108 
FRROR_UNABLE_TO_UNLOAD_MEDIA 1109 
ERROR_MEDIA_ CHANGED = 1110 
ERROR_BUS_RESET = 1111 
ERROR_NO_MEDIA_IN_DRIVE = 1112 
ERROR_NO_UNICODE_TRANSLATION = 1113 
EKRROR_DLL_INIT_FAILED = 1114 
ERROR_SHUTDOWN_IN_PROGRESS = 1115 
ERROR_NO_SHUTDOWN_IN_PROGRESS = 1116 
ERROR_IO_DEVICE = 1117 

ERROR_SERIAL_ NO_DEVICE = 1118 
ERROR_IRQ_ BUSY = 1119 
ERROR_MORE_WRITES = 1120 
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Const ERROR_COUNTER_TIMEOUT = 1121 

Const ERROR_FLOPPY_ID_MARK_NOT_FOUND = 1122 
Const ERROR_FLOPPY_WRONG_CYLINDER = 1123 
Const ERROR_FLOPPY_UNKNOWN_ERROR = 1124 
Const ERROR_FLOPPY_BAD REGISTERS = 1125 
Const ERROR_DISK_RECALIBRATE_ FAILED = 1126 
Const ERROR_DISK_OPERATION_FAILED = 1127 
Const ERROR_DISK_RESET_FAILED = 1128 

Const ERROR_EOM_OVERFLOW = 1129 

Const ERROR_NOT_ENOUGH_SERVER_MEMORY = 1130 
Const ERROR_POSSIBLE_ DEADLOCK = 1131 

Const ERROR_MAPPED_ ALIGNMENT = 1132 


Used By 


GetLastError, SetLastError, SetLastErrorEx 





Go back to the Other Information listing. 
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Manufacturer IDs 


Description & Usage 


The manufacturer IDs identify the manufacturer of a device. Normally, manufacturer IDs only apply to 
multimedia devices such as joysticks or audio devices. 


Visual Basic-Specific Issues 


None. 


Manufacturer IDs 


MM_ANTEX 

Antex Electronics Coporation 
MM_APPS 

APPS Software International 
MM_APT 

Audio Processing Technology 
MM_ARTISOFT 

Artisoft, Inc. 
MM_AST 

AST Research, Inc. 
MM_ATI 

ATI 
MM_AUDIOFILE 

Audio, Inc. 
MM_AUDIOPT 

Audio Processing Technology 
MM_AURAVISION 

AuraVision Corporation 
MM_AZTECH 

Aztech Labs, Inc. 
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MM_CANOPUS 

Canopus, Co., Ltd. 
MM_CAT 

Computer Aided Technologies 
MM_COMPUSIC 

Compusic 
MM_COMPUTER_FRIENDS 

Computer Friends, Inc. 
MM_CONTROLRES 

Control Resources Limited 
MM_CREATIVE 

Creative Labs, Inc. 
MM_DIALOGIC 

Dialogic Corporation 
MM_DOLBY 

Dolby Laboratories 
MM_DSP_GROUP 

DSP Group, Inc. 
MM_DSP_SOLUTIONS 

DSP Solutions, Inc. 
MM_ECHO 

Echo Speech Corporation 
MM_EPSON 

Seiko Epson Corporation 
MM_ESS 

ESS Technology 
MM_EVEREX 

Everex Systems, Inc. 
MM_EXAN 

EXAN 
MM_FUJITSU 

Fujitsu Corp. 
MM_GRAVIS 

Advanced Gravis 
MM_IBM 

IBM Corporation 
MM_ICL_PS 

ICL Personal Systems 
MM_ICS 

Integrated Circuit Systems, Inc. 
MM_INTEL 

Intel Corporation 
MM_INTERACTIVE 


http://216.26.168.92/vbapi/ref/other/manufacturerids.html (2 of 6) [9/1/2002 6:16:41 PM] 


Windows API Guide: Manufacturer IDs 


InterActive Inc. 
MM_IOMAGIC 

I/O Magic Corporation 
MM_ITERATEDSYS 

Iterated Systems, Inc. 
MM_KORG 

Toshihiko Okuhura, Korg Inc. 
MM_LOGITECH 

Logitech, Inc. 
MM_LYRRUS 

Lyrrus Inc. 
MM_MATSUSHITA 

Matsushita Electronic Industrial Co., Ltd. 
MM_MEDIAVISION 

Media Vision, Inc. 
MM_MELABS 

microEngineering Labs 
MM_METHEUS 

Metheus 
MM_MICROSOFT 

Microsoft Corporation. 
MM_MOSCOM 

MOSCOM Corporation 
MM_MOTOROLA 

Motorola, Inc. 
MM_NCR 

NCR Corporation 
MM_NEC 

NEC 
MM_NEWMEDIA 

New Media Corporation 
MM_NMS 

Natural MicroSystems 
MM_OKI 

OKI 
MM_OLIVETTI 

Olivetti 
MM_OPTI 

OPTi Computers Inc. 
MM_ROLAND 

Roland 
MM_SCALACS 

SCALACS 
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MM_SIERRA 

Sierra Semiconductor Corp. 
MM_SILICONSOFT 

Silicon Soft, Inc. 
MM_SONICFOUNDRY 

Sonic Foundry 
MM_SPEECHCOMP 

Speech Compression 
MM_SUPERMAC 

Supermac 
MM_TANDY 

Tandy Corporation 
MM_TRUEVISION 

Truevision 
MM_TURTLE_BEACH 

Turtle Beach, Inc. 
MM_VAL 

Video Associates Labs, Inc. 
MM_VIDEOLOGIC 

Videologic 
MM_VITEC 

Vitec Multimedia 
MM_VOCALTEC 

Vocaltec Ltd. 
MM_VOYETRA 

Voyetra 
MM_WANGLABS 

Wang Laboratories, Inc. 
MM_WILLOWPOND 

Willow Pond Corporation 
MM_WINNOV 

Winnov, Inc. 
MM_YAMAHA 

Yamaha Corporation of America 


Constant Definitions 


Const MM ANTEX = 31 


Const MM APPS = 42 


Const MM APT = 56 


Const MM_ARTISOFT = 20 


Const MM AST = 64 
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Const MM ATI = 27 


Const MM_AUDIOFILE = 47 


Const MM AUDIOPT = 74 


Const MM_AURAVISION = 80 


Const MM_AZTECH = 52 
Const MM_CANOPUS = 49 
Const MM_CAT = 41 

Const MM_COMPUSIC = 89 
Const MM _COMPUTER_FRIENDS = 45 
Const MM _CONTROLRES = 84 
Const MM _CREATIVE = 2 
Const MM_DIALOGIC 93 
Const MM_DOLBY = 78 

Const MM_DSP_GROUP = 43 
Const MM_DSP_SOLUTIONS = 25 
Const MM_ECHO = 39 

Const MM_EPSON = 50 

Const MM_ESS = 46 

Const MM_EVEREX = 38 
Const MM_EXAN = 63 

Const MM_FUJITSU = 4 
Const MM_GRAVIS = 34 
Const MM_IBM = 22 

Const MM_ICL_PS = 32 
Const MM_ICS = 57 

Const MM_INTEL = 33 

Const MM_INTERACTIVE = 36 
Const MM_IOMAGIC = 82 
Const MM_ITERATEDSYS = 58 
Const MM_KORG = 55 

Const MM_LOGITECH = 60 
Const MM_LYRRUS = 88 
Const MM_MATSUSHITA = 83 
Const MM_MEDIAVISION = 3 


Const MM MELABS = 44 


Const MM METHEUS = 59 


Const MM MICROSOFT = 1 


Const MM _MOSCOM = 68 


Const MM MOTOROLA = 48 


Const MM NCR = 62 


Const MM NEC = 26 


Const MM_NEWMEDIA = 86 


Const MM NMS = 87 
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Const MM OKI = 79 


Const MM_OLIVETTI 


Const MM OPTI = 90 


Const MM ROLAND = 24 


Const MM SCALACS = 54 


Const MM STERRA = 40 


Const MM_SILICONSOFT = 69 


Const MM SONICFOUNDRY = 66 


Const MM SPEECHCOMP = 76 


Const MM SUPERMAC = 73 


Const MM_TANDY = 29 


Const MM_TRUEVISION = 51 


Const MM_TURTLE BEACH = 21 
Const MM VAL = 35 


Const MM VIDEOLOGIC = 53 


Const MM VITEC = 67 


Const MM VOCALTEC = 23 


Const MM_VOYETRA = 30 


Const MM_WANGLABS = 28 


Const MM_WILLOWPOND = 65 


Const MM WINNOV = 61 


Const MM_YAMAHA 37 


Used By 


AUXCAPS, JOYCAPS, WAVEOUTCAPS 


81 








Go back to the Other Information listing. 
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MCI Command Strings 


Last Update: July 4, 2000 
Number of Command Strings Listed: 5 (5 added) 


MCI command strings are issued to MCI devices by using the mciSendString function. Command strings 
instruct a Media Control Interface (MCI) device to perform a specific action, such as opening a file, 
playing a CD, or stopping playback of a video. The MCI, through its command strings, provides a 
relatively simple way to control multimedia devices configured on the system. 


Below is a list of the MCI command strings that currently have information about them in the Windows 
API Guide. Please keep in mind that this site does not encompass the entire API yet, so unfortunately 
may not find what you are looking for. To suggest any additions you would like to see made, please 
contact the author with your request. All pages added since the last update of this site are clearly marked 


with NEW. 


e close NEW 
e open NEW 
e pause NEW 
e play NEW 
e stop NEW 


Back to Other API Information. 
Back to the Reference section. 
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close MCI Command String 


"close [pszDevicelD, lpszFlags" 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The close MCI command string closes a device or file previously opened by the open command. All resources used by the 
MCI device or file are freed, unless those resources are shared with other open devices or files. 


All MCI devices recognize the close command string. 


Return Value 


The close command string does not return any data. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpszDeviceID 
The device identifer string of the MCI device or file to close. This may be an alias to the device or file. 
lpszFlags 
Zero or more of the following options: 
"notify" 
When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to 


mciSendString. 
"wait" 
Do not have mciSendString return until the command finishes. 
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Example 


To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


' This code is licensed according to the terms and conditions listed here. 





' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 

















lpszCommand As String, ByVal lpszReturnString As String, ByVal 
cchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 
ublic Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
ByVal _ 








tg 























~ 

















fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 
As Long 














' Use the MCI to play or stop playback of a MIDI file. The file C:\Music\canyon.mid 
' is opened when the form opens. The Play and Stop buttons behave as you'd expect. 
The 

' only potential surprise is that the current position is not reset when playback 
stops; it 

' behaves just as pausing playback would. The file closes when the form unloads. 














F 


If anything goes wrong in the example, display a message box with 
' the MCI error message text. 


Private Sub Form_Load() 
' Open the file "C:\Music\canyon.mid" for later use in the example. 
' Give it an alias of "canyon" so we don't need to refer to the filename 
































again. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 

End Sub 





Private Sub cmdPlay_Click () 
' Begin playback of the MIDI file when this button is pressed. 
Dim errcode As Long ' MCI error code 























errcode = mciSendString("play canyon", "", 0, 0) 











If errcode <> 0 Then DisplayError errcode 
End Sub 








Private Sub cmdStop_Click () 
' Stop playback of the MIDI file when this button is pressed. 
' The position within the file does not move back to the beginning. 


Dim errcode As Long ' MCI error code 























errcode = mciSendString("stop canyon", "", 0, 0) 
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If errcode <> 0 Then DisplayError errcode 
End Sub 








Private Sub Form_Unload(Cancel As Integer) 














" Close the MIDI file when the form unloads. This is important, because the 
' MIDI driver can only work with one file at a time. There's no need to 
check 
' for an error here, since we're just closing the file. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("close canyon", "", 0, 0) 
End Sub 














Private Sub DisplayError (ByVal errcode As Long) 
' This subroutine displays a dialog box with the text of the MCI error. 








There's 











' no reason to use the MessageBox API function; VB's MsgBox function will 





suffice. 





Dim errstr As String ' MCI error message text 
Dim retval As Long ' return value 





' Get a string explaining the MCI error. 
errstr = Space(128) 
retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 














' Remove the terminating null and empty space at the end. 
errstr = Left(errstr, InStr(errstr, vbNullChar) - 1) 








' Display a simple error message box. 
retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 














See Also 


open 


Back to the MCI Command list. 
Back to Other API Information. 
Back to the Reference section. 
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open MCI Command String 


"open /pszDevice, lpszOpenFlags, lpszFlags" 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The open MCI command string opens a MCI device, initializing it for further use. One of the most useful features of open is 
the ability to assign an alias to a device, which makes referring to a file opened implicitly through a device simpler. Although 
in some cases it is not necessary to open a device before using it, it should be done nonetheless. Once your program is finished 
using the device, it should close it using the close command string. 


All MCI device types recognize the open command string. 


Return Value 


The open command string does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


IpszDevice 
The device identifier string of the MCI device or file to open. When opening a file, it will be manipulated through its 
typically associated device unless you use the "type" option in /pszOpenFlags to use a different device. For example, 
opening a MIDI file opens it through the sequencer. If this is "new", then a new resource is created; use the "type" 
option in /pszOpenFlags to specify the device type. 

lpszOpenFlags 
Zero or more of the following options for opening the device: 
"elementname" (digitalvideo) 

Specifies the file to load when the device opens. 
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"alias device_alias" (all) 
Assigns an alternate name that can be used in subsequent command strings. This is particularly useful to avoid 
referring to a lengthy filename multiple times. The device_alias can then be used in place of the device ID 
string. 
"puffer buffer_size" (waveaudio) 
Sets the size of the waveform audio device buffer, in seconds. Valid values range from 2 to 9 inclusive. 
"parent hwnd" (digitalvideo, overlay) 
Specifies a handle to the parent window for any windows the device may open. Windows opened by the device 
will become that window's children. 
"shareable" (all) 
Allow this particular instance of the device to be opened multiple times simultaneously, shared among any 
programs that wish to use it. However, the MCISEQ and MCIWAVE drivers do not support sharing. 
"style child" (digitalvideo, overlay) 
Open a window with the style of a child window. 
"style overlapped" (digitalvideo, overlay) 
Open a window with the style of an overlapped (regular) window. 
"style popup" (digitalvideo, overlay) 
Open a window with the style of a pop-up window. 
"style style_type" (digitalvideo, overlay) 
Open a window with the specified style. style_type is the numerical value of one of the following flags: 
SW_HIDE 
Hide the window. 
SW_MAXIMIZE 
Maximize the window. 
SW_MINIMIZE 
Minimize the window. 
SW_RESTORE 
Restore the window (not maximized nor minimized). 
SW_SHOW 
Show the window. 
SW_SHOWMAXIMIZED 
Show the window maximized. 
SW_SHOWMINIMIZED 
Show the window minimized. 
SW_SHOWMINNOACTIVE 
Show the window minimized but do not activate it. 
SW_SHOWNA 
Show the window in its current state but do not activate it. 
SW_SHOWNOACTIVATE 
Show the window in its most recent size and position but do not activate it. 
SW_SHOWNORMAL 
Show the window and activate it (as usual). 
"type device_type" (all) 
When opening a new instance of a device, this specifies the type of device being opened. Remember that "new" 
was specified as /pszDevice. 





lpszFlags 
Zero or more of the following options: 
"notify" 
When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to 
mciSendString. 
"wait" 
Do not have mciSendString return until the command finishes. 
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Constant Definitions 











































































































Const SW_HIDE = 0 

Const SW_MAXIMIZE = 3 

Const SW_MINIMIZE = 6 

Const SW_RESTORE = 9 

Const SW_SHOW = 5 

Const SW_SHOWMAXIMIZED = 3 
Const SW_SHOWMINIMIZED = 2 
Const SW_SHOWMINNOACTIVE = 7 
Const SW_SHOWNA = 8 

Const SW_SHOWNOACTIVATE = 4 
Const SW_SHOWNORMAL = 1 


Example 


To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


' This code is licensed according to the terms and conditions listed here. 








' Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 























lpszCommand As String, ByVal lpszReturnString As String, ByVal 
cchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 
ublic Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
ByVal _ 











tg 























~ 




















fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 





As Long 

















' Use the MCI to play or stop playback of a MIDI file. The file C:\Music\canyon.mid 
' is opened when the form opens. The Play and Stop buttons behave as you'd expect. 
The 

' only potential surprise is that the current position is not reset when playback 
stops; it 

' behaves just as pausing playback would. The file closes when the form unloads. 




















' If anything goes wrong in the example, display a message box with 
' the MCI error message text. 








Private Sub Form_Load() 
' Open the file "C:\Music\canyon.mid" for later use in the example. 


E 


' Give it an alias of "canyon" so we don't need to refer to the filename 














again. 





Dim errcode As Long ' MCI error code 


errcode = mciSendString ("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
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If errcode <> 0 Then DisplayError errcode 
End Sub 
Private Sub cmdPlay_Click () 

' Begin playback of the MI 











Dim errcode As Long MCI error code 


errcode 


mciSendString ("play canyon", 


If errcode <> 0 Then 
End Sub 


wee 
r 





Error errcode 











Display] 





Private Sub cmdStop_Click () 
' Stop playback of the MI 
The position within the 


Dim errcode As Long ' MCI error code 


DI file when this 


file does not 














errcode 
If errcode <> 0 Then 
End Sub 


moiSendString ("stop canyon", 


wee 
r 





Error errcode 








Display] 











Private Sub Form_Unload(Cancel As Integer) 


' Close the MIDI file when the 









































form unloads. 


DI file when this button is pressed. 


0, OQ) 


button is pressed. 


move back to the beginning. 


0, 0) 


This is important, because the 


















































' MIDI driver can only work with one file at a time. There's no need to 
check 

' for an error here, since we're just closing the file. 

Dim errcode As Long ' MCI error code 

errcode = mciSendString("close canyon", "", 0, 0) 
End Sub 
Private Sub DisplayError (ByVal errcode As Long) 

' This subroutine displays a dialog box with the text of the MCI error. 
There's 

' no reason to use the MessageBox API function; VB's MsgBox function will 
suffice. 

Dim errstr As String ' MCI error message text 

Dim retval As Long ' return value 

' Get a string explaining the MCI error. 

errstr = Space(128) 

retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 

' Remove the terminating null and empty space at the end. 

errstr = Left(errstr, InStr(errstr, vbNullChar) - 1) 

' Display a simple error message box. 

retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 


See Also 


close 
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Back to the MCI Command list. 
Back to Other API Information. 
Back to the Reference section. 
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pause MCI Command String 


"pause [pszDevicelD, IpszFlags" 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The pause MCI command string pauses playback of an playing MCI device. Typically, the current position does not change as 
a result of pausing playback. 


The following MCI device types recognize the stop command string: cdaudio, digitalvideo, sequencer, vcr, videodisk, 
waveaudio. 


Return Value 


The pause command string does not return any data. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpszDeviceID 
The device identifer string of the MCI device or file to pause. This may be an alias to the device or file. 
lpszFlags 
Zero or more of the following options: 
"notify" 
When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to 
mciSendString. 
"test" (digitalvideo and vcr only) 
Test to see if the device supports the pause command. The device is not actually paused, and the call to 
mciSendString only returns successfully if the device supports the pause command. 
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"wait" 


Do not have mciSendString return until the command finishes. 


Example 


To run this code, place three command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Name another one "cmdStop" and set its Caption to "&Stop MIDI File". Finally, if you haven't figured it out yet, name 
the last one "cmdPause" and set its Caption to "&Pause MIDI File". 














This code is licensed according to the terms and conditions listed here. 


Declarations and such needed for the example: 
















































































' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 
lpszCommand As String, ByVal lpszReturnString As String, ByVal 
ecchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 
Public Declare Function mciGetErrorString Lib "winmm.dll1" Alias "mciGetErrorStringA" 
(ByVal _ 
fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 
As Long 
' Use the MCI to play, stop, or pause playback of a MIDI file. The file 


Cs 


\Music\canyon.mid 





' is opened when th 
' only potential 
it 

behaves just as pausing playback would. 


stops; 


F 





Private 














If anything goes wrong in the example, 
' the MCI 


form opens. 
surprise 


The various buttons behave as you'd expect. The 
is that the current position is not reset when playback 











The file closes when the form unloads. 
display a message box with 


error message text. 


Sub Form_Load() 

































































' Open the file "C:\Music\canyon.mid" for later use in the example. 
' Give it an alias of "canyon" so we don't need to refer to the filename 
again. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 
Private Sub cmdPlay_Click () 
' Begin playback of the MIDI file when this button is pressed. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("play canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 
Private Sub cmdStop_Click 


() 





Stop playback of 





the MIDI file when this button is pressed. 
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End Sub 


Private 





End Sub 


Private 


check 





End Sub 


Private 


There's 


su 








ffice. 


End Sub 


' The position within the file does not move back to the beginning. 
Dim errcode As Long ' MCI error code 





errcode = mciSendString("stop canyon", "", 0, 0) 











If errcode <> 0 Then DisplayError errcode 





Sub cmdPause_Click () 

' Pause playback of the MIDI file when this button is pressed. 

' The position within the file, naturally, does not revert to the beginning. 
Dim errcode As Long ' MCI error code 

















errcode = mciSendString ("pause canyon", "", 0, 0) 

















If errcode <> 0 Then DisplayError errcode 








Sub Form_Unload(Cancel As Integer) 
' Close the MIDI file when the form unloads. This is important, because the 
' MIDI driver can only work with one file at a time. There's no need to 


























' for an error here, since we're just closing the file. 
Dim errcode As Long ' MCI error code 





errcode = mciSendString("close canyon", "", 0, 0) 














Sub DisplayError (ByVal errcode As Long) 
' This subroutine displays a dialog box with the text of the MCI error. 














' no reason to use the MessageBox API function; VB's MsgBox function will 





Dim errstr As String ' MCI error message text 
Dim retval As Long " return value 





' Get a string explaining the MCI error. 
errstr = Space(128) 
retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 

















' Remove the terminating null and empty space at the end. 
errstr = Left(errstr, InStr(errstr, vbNullChar) - 1) 














' Display a simple error message box. 
retval = MsgBox(errstr, vbOKOnly Or vbCritical) 











See Also 


play, stop 


Back to the MCI Command list. 





Back to Other API Information. 





Back to the Reference section. 
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play MCI Command String 


"play lpszDevicelD, IpszPlayFlags, lpszFlags" 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The play MCI command string begins playing a MCI device. By default, playback begins at the current position in the device. 
Of course, this default can be overridden by options specified in /pszPlayFlags. 


The following MCI device types recognize the play command string: cdaudio, digitalvideo, sequencer, vcr, videodisk, 
waveaudio. 


Return Value 


The play command string does not return a value. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpszDeviceID 
The device identifer string of the MCI device or file to play. This may be an alias to the device or file. 
lpszPlayFlags 
Zero or more of the following options for how to play the MCI device: 
"at time" (vcr) 
Specifies when the device should begin playback, especially if it has previously been cued. 
"fast" (videodisc) 
Play the device at a speed faster than normal. 
"from position" (all) 
Specifies the position at which to begin playback. If nothing is specified for position, playback begins at the 
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current position. 

"fullscreen" (digitalvideo) 
Use a full-screen display. This option only works when playing a compressed file. 

"repeat" (digitalvideo) 
Restart playback once the end has been reached. 

"reverse" (digitalvideo, vcr, videodisc) 
Play the device backwards. When using this option, the "to" option cannot be used. 

"scan" (vcr, videodisc) 
Play as fast as possible without disabling video display, although audio may be disabled. This is essentially fast- 
forwarding the device. 

"slow" (videodisc) 
Play the device at a speed slower than normal. 

"speed integer" (videodisc) 
Play the videodisc at integer frames per second. 

"to position" (all) 
Specifies the position at which to end playback. If nothing is specified for position, playback ends until the end 
of the device is reached. 

"window" (digitalvideo) 
Use the window associated with the device's instance to display the video. 

lpszFlags 

Zero or more of the following options: 

"notify" 
When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to 
mciSendsString. 

"test" (digitalvideo and vcr only) 
Test to see if the device supports the play command. Nothing is played, and the call to mciSendString only 
returns successfully if the device supports the play command. 

"wait" 
Do not have mciSendString return until the command finishes. 








Example 
To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 
' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 
lpszCommand As String, ByVal lpszReturnString As String, ByVal 

ecchReturnLength _ 

As Long, ByVal hwndCallback As Long) As Long 
ublic Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
ByVal _ 























AG) 























~ 




















fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 








As Long 








' Use the MCI to play or stop playback of a MIDI file. The file C:\Music\canyon.mid 
' is opened when the form opens. The Play and Stop buttons behave as you'd expect. 
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The 


" only potential surprise is that the current position is not reset when playback 


stops; 


Te 








' behaves just as pausing playback would. The file closes when the form unloads. 


' If anything goes wrong in the example, display a message box with 
' the MCI error message text. 


Private 


again. 


End Sub 





Private 


End Sub 





Private 


End Sub 





Private 


check 


End Sub 





Private 


There's 


suffice. 


Sub Form_Load() 
' Open the file "C:\Music\canyon.mid" for later use in the example. 


T 


' Give it an alias of "canyon" so we don't need to refer to the filename 











Dim errcode As Long ' MCI error code 


errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0) 











If errcode <> 0 Then DisplayError errcode 





Sub cmdPlay_Click () 














' Begin playback of the MIDI file when this button is pressed. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("play canyon", "", 0, 0) 














If errcode <> 0 Then DisplayError errcode 





Sub cmdStop_Click () 

' Stop playback of the MIDI file when this button is pressed. 

' The position within the file does not move back to the beginning. 
Dim errcode As Long ' MCI error code 




















errcode = mciSendString("stop canyon", "", 0, 0) 











If errcode <> 0 Then DisplayError errcode 


Sub Form_Unload(Cancel As Integer) 
' Close the MIDI file when the form unloads. This is important, because the 
' MIDI driver can only work with one file at a time. There's no need to 








' for an error here, since we're just closing the file. 
Dim errcode As Long ' MCI error code 





errcode = mciSendString("close canyon", "", 0, 0) 

















Sub DisplayError (ByVal errcode As Long) 
' This subroutine displays a dialog box with the text of the MCI error. 











' no reason to use the MessageBox API function; VB's MsgBox function will 





Dim errstr As String ' MCI error message text 
Dim retval As Long ' return value 
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' Get a string explaining the MCI error. 
errstr = Space(128) 
retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 


' 

















Remove the terminating null and empty space at the end. 
errstr = Left(errstr, InStr(errstr, voNullChar) - 1) 














Display a simple error message box. 
retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 











See Also 


pause, stop 


Back to the MCI Command list. 
Back to Other API Information. 
Back to the Reference section. 
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stop MCI Command String 


"stop [pszDevicelD, IpszStopFlags, IpszFlags" 


Platforms 


Windows 95: Supported. 

Windows 98: Supported. 

Windows NT: Requires Windows NT 3.1 or later. 
Windows 2000: Supported. 

Windows CE: Not Supported. 


Description & Usage 


The stop MCI command string stops playback of an playing MCI device. For audio CDs, the current position is reset to the 
beginning of the track that had been playing. For all other MCI devices, the current position remains where it had been playing. 


The following MCI device types recognize the stop command string: cdaudio, digitalvideo, sequencer, ver, videodisk, 
waveaudio. 


Return Value 


The stop command string does not return any data. 


Visual Basic-Specific Issues 


None. 


Parameters 


lpszDeviceID 
The device identifer string of the MCI device or file to stop playback of. This may be an alias to the device or file. 
lpszStopFlags 
The following option may be specified only for digitalvideo devices: 
"hold" 
Do not release the resources needed to draw the current still image on the screen. This allows the currently 
displayed frame of the stopped video to be redrawn as necessary (for example, if the playback window moves). 
lpszFlags 
Zero or more of the following options: 
"notify" 
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When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to 
mciSendString. 

"wait" 
Do not have mciSendString return until the command finishes. 








Example 


To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI 
File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File". 


This code is licensed according to the terms and conditions listed here. 





Declarations and such needed for the example: 

' (Copy them to the (declarations) section of a module.) 
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _ 

lpszCommand As String, ByVal lpszReturnString As String, ByVal 
ecchReturnLength _ 
As Long, ByVal hwndCallback As Long) As Long 

ublic Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" 
ByVal _ 























tg 























~ 














fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) 











As Long 

















' Use the MCI to play or stop playback of a MIDI file. The file C:\Music\canyon.mid 
' is opened when the form opens. The Play and Stop buttons behave as you'd expect. 
The 

' only potential surprise is that the current position is not reset when playback 
stops; it 

' behaves just as pausing playback would. The file closes when the form unloads. 














F 


If anything goes wrong in the example, display a message box with 
the MCI error message text. 


Private Sub Form_Load() 












































' Open the file "C:\Music\canyon.mid" for later use in the example. 
' Give it an alias of "canyon" so we don't need to refer to the filename 
again. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0) 
If errcode <> 0 Then DisplayError errcode 
End Sub 





Private Sub cmdPlay_Click () 
' Begin playback of the MIDI file when this button is pressed. 
Dim errcode As Long ' MCI error code 

















errcode = mciSendString("play canyon", "", 0, 0) 

















If errcode <> 0 Then DisplayError errcode 











End Sub 
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Private Sub cmdStop_Click () 








' Stop playback of the MIDI file when this button is pressed. 
' The position within the file does not move back to the beginning. 











Dim errcode As Long ' MCI error code 


errcode = mciSendString("stop canyon", "", 0, 0) 

















If errcode <> 0 Then DisplayError errcode 
End Sub 





Private Sub Form_Unload(Cancel As Integer) 























There's no need to 


' Close the MIDI file when the form unloads. This is important, because the 
' MIDI driver can only work with one file at a time. 
check 
' for an error here, since we're just closing the file. 
Dim errcode As Long ' MCI error code 
errcode = mciSendString("close canyon", "", 0, 0) 
End Sub 














Private Sub DisplayError (ByVal errcode As Long) 








' This subroutine displays a dialog box with the 
There's 





' no reason to use the MessageBox API function; 





suffice. 





Dim errstr As String ' MCI error message text 
Dim retval As Long " return value 





' Get a string explaining the MCI error. 
errstr = Space(128) 








Vi 


text of 








B's Msgl 


retval = mciGetErrorString(errcode, errstr, Len(errstr) ) 











the MCI error. 


Box function will 


' Remove the terminating null and empty space at the end. 








errstr = Left(errstr, InStr(errstr, voNullChar) 








' Display a simple error message box. 
retval = MsgBox(errstr, vbOKOnly Or vbCritical) 
End Sub 











See Also 


pause, play 


Back to the MCI Command list. 
Back to Other API Information. 
Back to the Reference section. 








Last Modified: July 4, 2000 


1) 


This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000 





Go back to the Windows API Guide home page. 
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E-mail: vbapi@ vbapi.com Send Encrypted E-Mail 





This page is at http://www.vbapi.com/ref/other/mci/stop.html 
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vbapi.com - part of the VB-World Network 


WHITE | CLIFF 


| www.vbworld.com | www.vbforums.com | www.vbsquare.com | 
www.vbapi.com | www.vb-shop.com | 





Product Identifiers 


Description & Usage 


The product identifiers identify the product name or type of a device. The following flags list the 
product IDs defined by the Windows API. Note that the manufacturer ID of the device must be known to 


select the proper device ID. The device IDs below are grouped accorording to manufacturer. (The 
manufacturer ID associated with each manufacturer is also shown.) 


Visual Basic-Specific Issues 


None. 


Product Identifiers (Grouped by Manufacturer) 


e Audio Processing Technology (MM_APT) Product IDs: 
MM_APT_ACE100CD 
ACE 100 CD. 
e Artisoft, Inc. (MM_ARTISOFT) Product IDs: 
MM_ARTISOFT_SBWAVEIN 
Artisoft Sounding Board waveform input. 
MM_ARTISOFT_SBWAVEOUT 
Artisoft Sounding Board waveform output. 
e Aztech Labs, Inc. (MM_AZTECH) Product IDs: 
MM_AZTECH_AUX_CD 
Aztech auxiliary CD. 
MM_AZTECH_AUX_LINE 
Aztech auxiliary line input. 
MM_AZTECH_AUX_MIC 
Aztech auxiliary microphone. 
MM_AZTECH_AUX 
Aztech auxiliary. 
MM_AZTECH_DSP16_WAVEIN 
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Aztech DSP 16 waveform input. 
MM_AZTECH_DSP16_WAVEOUT 

Aztech DSP 16 waveform output. 
MM_AZTECH_DSP16_FMSYNTH 

Aztech DSP 16 FM synthesizer. 
MM_AZTECH_DSP16_WAVESYNTH 

Aztech DSP 16 waveform synthesizer. 
MM_AZTECH_NOVA16_WAVEIN 

Aztech Nova 16 waveform input. 
MM_AZTECH_NOVA16_WAVEOUT 

Aztech Nova 16 waveform output. 
MM_AZTECH_NOVA16_MIXER 

Aztech Nova 16 mixer. 
MM_AZTECH_PRO16_WAVEIN 

Aztech Pro 16 waveform input. 
MM_AZTECH_PRO16_WAVEOUT 

Aztech Pro 16 waveform output. 
MM_AZTECH_PRO16_FMSYNTH 

Aztech Pro 16 FM synthesizer. 
MM_AZTECH_WASH16_WAVEIN 

Aztech Wash 16 waveform input. 
MM_AZTECH_WASH16_WAVEOUT 

Aztech Wash 16 waveform output. 
MM_AZTECH_WASH16_MIXER 

Aztech Wash 16 mixer. 
MM_AZTECH_MIDIOUT 

Aztech MIDI output. 
MM_AZTECH_MIDIIN 

Aztech MIDI input. 
MM_AZTECH_WAVEIN 

Aztech waveform input. 
MM_AZTECH_WAVEOUT 

Aztech waveform output. 
MM_AZTECH_FMSYNTH 

Aztech FM synthesizer. 
MM_AZTECH_MIXER 

Aztech mixer. 

e Computer Aided Technologies (MM_CAT) Product IDs: 

MM_CAT_WAVEOUT 

Waveform output. 

e Creative Labs, Inc. (MM_CREATIVE) Product IDs: 

MM_CREATIVE_AUX_CD 

Sound Blaster Pro auxiliary CD. 
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MM_CREATIVE_AUX_LINE 

Sound Blaster Pro auxiliary line input. 
MM_CREATIVE_AUX_MIC 

Sound Blaster Pro auxiliary microphone. 
MM_CREATIVE_AUX_MASTER 

Sound Blaster Pro auxiliary master. 
MM_CREATIVE_AUX_PCSPK 

Sound Blaster Pro auxiliary PC speaker. 
MM_CREATIVE_AUX_WAVE 

Sound Blaster Pro auxiliary waveform. 
MM_CREATIVE_AUX_MIDI 

Sound Blaster Pro auxiliary MIDI. 
MM_CREATIVE_SB15_WAVEIN 

Sound Blaster 1.5 waveform input. 
MM_CREATIVE_SB15_WAVEOUT 

Sound Blaster 1.5 waveform output. 
MM_CREATIVE_SB16_MIXER 

Sound Blaster Pro 16 mixer. 
MM_CREATIVE_SB20_WAVEIN 

Sound Blaster 2.0 waveform input. 
MM_CREATIVE_SB20_WAVEOUT 

Sound Blaster 2.0 waveform output. 
MM_CREATIVE_SBP16_WAVEIN 

Sound Blaster Pro 16 waveform input. 
MM_CREATIVE_SBP16_WAVEOUT 

Sound Blaster Pro 16 waveform output. 
MM_CREATIVE_SBPRO_WAVEIN 

Sound Blaster Pro waveform input. 
MM_CREATIVE_SBPRO_WAVEOUT 

Sound Blaster Pro waveform output. 
MM_CREATIVE_SBPRO_MIXER 

Sound Blaster Pro mixer. 
MM_CREATIVE_MIDIOUT 

Sound Blaster MIDI output. 
MM_CREATIVE_MIDIIN 

Sound Blaster MIDI input. 
MM_CREATIVE_FMSYNTH_MONO 

Sound Blaster mono FM synthesizer. 
MM_CREATIVE_FMSYNTH_STEREO 

Sound Blaster stereo FM synthesizer. 
MM_CREATIVE_MIDI_AWE32 

Sound Blaster MIDI AWE 32. 

e DSP Group, Inc. (MM_DSP_GROUP) Product IDs: 
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MM_DSP_GROUP_TRUESPEECH 
True Speech. 
e DSP Solutions, Inc. (MM_DSP_SOLUTIONS) Product IDs: 
MM_DSP_SOLUTIONS_WAVEOUT 
DSP Solutions waveform output. 
MM_DSP_SOLUTIONS_WAVEIN 
DSP Solutions waveform input. 
MM_DSP_SOLUTIONS_SYNTH 
DSP Solutions synthesizer. 
MM_DSP_SOLUTIONS_AUX 
DSP Solutions auxiliary. 
e Echo Speech Corporation (MM_ECHO) Product IDs: 
MM_ECHO_SYNTH 
Echo synthesizer. 
MM_ECHO_WAVEOUT 
Echo waveform output. 
MM_ECHO_WAVEIN 
Echo waveform input. 
MM_ECHO_MIDIOUT 
Echo MIDI output. 
MM_ECHO_MIDIIN 
Echo MIDI input. 
MM_ECHO_AUX 
Echo auxiliary. 
e ESS Technology (MM_ESS) Product IDs: 
MM_ESS_AMWAVEOUT 
AM waveform output. 
MM_ESS_AMWAVEIN 
AM waveform input. 
MM_ESS_AMAUX 
AM auxiliary. 
MM_ESS_AMSYNTH 
AM synthesizer. 
MM_ESS_AMMIDIOUT 
AM MIDI output. 
MM_ESS_AMMIDIIN 
AM MIDI input. 
MM_ESS_AUX_CD 
Auxiliary CD. 
MM_ESS_ES488_WAVEOUT 
ES488 waveform output. 
MM_ESS_ES488_WAVEIN 
ES488 waveform input. 
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MM_ESS_ES488_MIXER 
ES488 mixer. 
MM_ESS_ES688_WAVEOUT 
ES688 waveform output. 
MM_ESS_ES688_WAVEIN 
ES488 waveform input. 
MM_ESS_ES688_MIXER 
ES488 mixer. 
MM_ESS_ES1488_WAVEOUT 
ES1488 waveform output. 
MM_ESS_ES1488_WAVEIN 
ES1488 waveform input. 
MM_ESS_ES1488_MIXER 
ES1488 mixer. 
MM_ESS_ES1688_WAVEOUT 
ES1688 waveform output. 
MM_ESS_ES1688_WAVEIN 
ES1688 waveform input. 
MM_ESS_ES1688_MIXER 
ES1688 mixer. 
MM_ESS_MPU401_MIDIOUT 
MPU401 MIDI output. 
MM_ESS_MPU401_MIDIIN 
MPU401 MIDI input. 
MM_ESS_MIXER 
Mixer. 
e Everex Systems, Inc. (MM_EVEREX) Product IDs: 
MM_EVEREX_CARRIER 
Everex Carrier. 
e IBM Corporation (MM_IBM) Product IDs: 
MM_IBM_PCMCIA_WAVEIN 
IBM PCMCIA waveform input. 
MM_IBM_PCMCIA_WAVEOUT 
IBM PCMCIA waveform output. 
MM_IBM_PCMCIA_SYNTH 
IBM PCMCIA synthesizer. 
MM_IBM_PCMCIA_MIDIIN 
IBM PCMCIA MIDI input. 
MM_IBM_PCMCIA_MIDIOUT 
IBM PCMCIA MIDI output. 
MM_IBM_PCMCIA_AUX 
IBM PCMCIA auxiliary. 
MM_MMOTION_WAVEAUX 
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IBM M-Motion auxiliary. 
MM_MMOTION_WAVEOUT 
IBM M-Motion waveform output. 
MM_MMOTION_WAVEIN 
IBM M-Motion waveform input. 
e Integrated Circuit Systems, Inc. (MM_ICS) Product IDs: 
MM_ICS_WAVEDECK_WAVEOUT 
Wavedeck waveform output. 
MM_ICS_WAVEDECK_WAVEIN 
Wavedeck waveform input. 
MM_ICS_WAVEDECK_MIXER 
Wavedeck mixer. 
MM_ICS_WAVEDECK_AUX 
Wavedeck auxiliary. 
MM_ICS_WAVEDECK_SYNTH 
Wavedeck synthesizer. 
e InterActive, Inc. (MM_INTERACTIVE) Product IDs: 
MM_INTERACTIVE_WAVEIN 
InterActive waveform input. 
MM_INTERACTIVE_WAVEOUT 
InterActive waveform output. 
e I/O Magic Corporation (MM_IOMAGIC) Product IDs: 
MM_IOMAGIC_TEMPO_WAVEOUT 
Tempo waveform output. 
MM_IOMAGIC_TEMPO_WAVEIN 
Tempo waveform input. 
MM_IOMAGIC_TEMPO_SYNTH 
Tempo synthesizer. 
MM_IOMAGIC_TEMPO_MIDIOUT 
Tempo MIDI output. 
MM_IOMAGIC_TEMPO_MXDOUT 
Tempo mixed output. 
MM_IOMAGIC_TEMPO_AUXOUT 
Tempo auxiliary output. 
e Iterated Systems, Inc. (MM_ITERATEDSYS) Product IDs: 
MM_ITERATED_SYS_FUFCODEC 
FUF Codec. 
e Toshihiko Okuhura, Korg Inc. (MM_KORG) Product IDs: 
MM_KORG_PCIF_MIDIOUT 
PCIF MIDI output. 
MM_KORG_PCIF_MIDIIN 
PCIF MIDI input. 
e Lyrrus, Inc. (MM_LYRRUS) Product IDs: 
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MM_LYRRUS_BRIDGE_GUITAR 

Bridge Guitar MIDI. 

e Matsushita Electronic Industrial Co., Ltd. (MM MATSUSHITA) Product IDs: 

MM_MATSUSHITA_WAVEIN 

Matsushita waveform input. 
MM_MATSUSHITA_WAVEOUT 

Matsushita waveform output. 
MM_MATSUSHITA_FMSYNTH_STEREO 

Matsushita FM stereo synthesizer. 
MM_MATSUSHITA_MIXER 

Matsushita mixer. 
MM_MATSUSHITA_AUX 

Matsushita auxiliary. 

e Media Vision, Inc. (MM_MEDIAVISION) Product IDs: 

MM_CDPC_MIDIOUT 

CDPC MIDI output. 
MM_CDPC_MIDIIN 

CDPC MIDI input. 
MM_CDPC_SYNTH 

CDPC synthesizer. 
MM_CDPC_WAVEOUT 

CDPC waveform output. 
MM_CDPC_WAVEIN 

CDPC waveform input. 
MM_CDPC_MIXER 

CDPC mixer. 
MM_CDPC_AUX 

CDPC auxiliary. 
MM_OPUS1208_MIDIOUT 

Opus MV 1208 Chipset MIDI output. 
MM_OPUS1208_MIDIIN 

Opus MV 1208 Chipset MIDI input. 
MM_OPUS1208_SYNTH 

Opus MV 1208 Chipset synthesizer. 
MM_OPUS1208_WAVEOUT 

Opus MV 1208 Chipset waveform output. 
MM_OPUS1208_WAVEIN 

Opus MV 1208 Chipset waveform input. 
MM_OPUS1208_MIXER 

Opus MV 1208 Chipset mixer. 
MM_OPUS1208_AUX 

Opus MV 1208 Chipset auxiliary. 
MM_OPUS1216_MIDIOUT 
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Opus MV 1216 Chipset MIDI output. 
MM_OPUS1216_MIDIIN 

Opus MV 1216 Chipset MIDI input. 
MM_OPUS1216_SYNTH 

Opus MV 1216 Chipset synthesizer. 
MM_OPUS1216_WAVEOUT 

Opus MV 1216 Chipset waveform output. 
MM_OPUS1216_WAVEIN 

Opus MV 1216 Chipset waveform input. 
MM_OPUS1216_MIXER 

Opus MV 1216 Chipset mixer. 
MM_OPUS1216_AUX 

Opus MV 1216 Chipset auxiliary. 
MM_PROAUD_MIDIOUT 

Pro Audio Spectrum MIDI output. 
MM_PROAUD_MIDIIN 

Pro Audio Spectrum MIDI input. 
MM_PROAUD_SYNTH 

Pro Audio Spectrum synthesizer. 
MM_PROAUD_WAVEOUT 

Pro Audio Spectrum wavefrom output. 
MM_PROAUD_WAVEIN 

Pro Audio Spectrum waveform input. 
MM_PROAUD_MIXER 

Pro Audio Spectrum mixer. 
MM_PROAUD_AUX 

Pro Audio Spectrum auxiliary. 
MM_PROAUD_16_MIDIOUT 

Pro Audio Spectrum 16 MIDI output. 
MM_PROAUD_16_MIDIIN 

Pro Audio Spectrum 16 MIDI input. 
MM_PROAUD_16_SYNTH 

Pro Audio Spectrum 16 synthesizer. 
MM_PROAUD_16_WAVEOUT 

Pro Audio Spectrum 16 waveform output. 
MM_PROAUD_16_WAVEIN 

Pro Audio Spectrum 16 waveform input. 
MM_PROAUD_16_MIXER 

Pro Audio Spectrum 16 mixer. 
MM_PROAUD_16_AUX 

Pro Audio Spectrum 16 auxiliary. 
MM_PROAUD_PLUS_MIDIOUT 

Pro Audio Spectrum Plus MIDI output. 
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MM_PROAUD_PLUS_MIDIIN 

Pro Audio Spectrum Plus MIDI input. 
MM_PROAUD_PLUS_SYNTH 

Pro Audio Spectrum Plus synthesizer. 
MM_PROAUD_PLUS_WAVEOUT 

Pro Audio Spectrum Plus waveform output. 
MM_PROAUD_PLUS_WAVEIN 

Pro Audio Spectrum Plus waveform input. 
MM_PROAUD_PLUS_MIXER 

Pro Audio Spectrum Plus mixer. 
MM_PROAUD_PLUS_AUX 

Pro Audio Spectrum Plus auxiliary. 
MM_STUDIO_16_MIDIOUT 

Pro Audio Studio 16 MIDI output. 
MM_STUDIO_16_MIDIIN 

Pro Audio Studio 16 MIDI input. 
MM_STUDIO_16_SYNTH 

Pro Audio Studio 16 synthesizer. 
MM_STUDIO_16_WAVEOUT 

Pro Audio Studio 16 waveform output. 
MM_STUDIO_16_WAVEIN 

Pro Audio Studio 16 waveform input. 
MM_STUDIO_16_MIXER 

Pro Audio Studio 16 mixer. 
MM_STUDIO_16_AUX 

Pro Audio Studio 16 auxiliary. 
MM_THUNDER_SYNTH 

Thunder Board synthesizer. 
MM_THUNDER_WAVEOUT 

Thunder Board waveform output. 
MM_THUNDER_WAVEIN 

Thunder Board waveform input. 
MM_THUNDER_AUX 

Thunder Board auxiliary. 
MM_TPORT_WAVEOUT 

Audio Port waveform output. 
MM_TPORT_WAVEIN 

Audio Port waveform input. 
MM_TPORT_SYNTH 

Audio Port synthesizer. 

e microEngineering Labs (MM_MELABS) Product IDs: 

MM_MELABS_MIDI2GO 

MIDI 2 Go. 
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e Metheus (MM_METHEUS) Product IDs: 

MM_METHEUS_ZIPPER 

Zipper. 

e Microsoft (MM_MICROSOFT) Product IDs: 

MM_MIDI_MAPPER 

MIDI mapper. 
MM_WAVE_MAPPER 

Waveform mapper. 
MM_SNDBLST_MIDIOUT 

Sound Blaster MIDI output port. 
MM_SNDBLST_MIDIIN 

Sound Blaster MIDI input port. 
MM_SNDBLST_SYNTH 

Sound Blaster internal synthesizer. 
MM_SNDBLST_WAVEOUT 

Sound Blaster waveform output. 
MM_SNDBLST_WAVEIN 

Sound Blaster waveform input. 
MM_ADLIB 

Ad Lib-compatible synthesizer. 
MM_MPU401_MIDIOUT 

MPU 401-compatible MIDI output port. 
MM_MPU401_MIDIIN 

MPU 401-compatible MIDI input port. 
MM_PC_JOYSTICK 

Joystick adapter. 
MM_PCSPEAKER_WAVEOUT 

PC Speaker waveform output. 
MM_MSFT_WSS_WAVEIN 

Microsoft Audio Board waveform input. 
MM_MSFT_WSS_WAVEOUT 

Microsoft Audio Board waveform output. 
MM_MSFT_WSS_FMSYNTH_STEREO 

Microsoft Audio Board stereo FM synthesizer. 
MM_MSFT_WSS_MIXER 

Microsoft Audio Board mixer driver. 
MM_MSFT_WSS_OEM_WAVEIN 

Microsoft OEM Audio Board waveform input. 
MM_MSFT_WSS_OEM_WAVEOUT 

Microsoft OEM Audio Board waveform output. 
MM_MSFT_WSS_OEM_FMSYNTH_STEREO 

Microsoft OEM Audio Board stereo FM synthesizer. 
MM_MSFT_WSS_AUX 


http://216.26.168.92/vbapi/ref/other/productids.html (10 of 26) [9/1/2002 6:19:18 PM] 


Windows API Guide: Product Identifiers 


Microsoft Audio Board auxiliary port. 
MM_MSFT_WSS_OEM_AUX 

Microsoft OEM Audio Board auxiliary port. 
MM_MSFT_GENERIC_WAVEIN 

Microsoft Vanilla driver waveform input. 
MM_MSFT_GENERIC_WAVEOUT 

Microsoft Vanilla driver waveform output. 
MM_MSFT_GENERIC_MIDIIN 

Microsoft Vanilla driver MIDI input. 
MM_MSFT_GENERIC_MIDIOUT 

Microsoft Vanilla driver MIDI output. 
MM_MSFT_GENERIC_MIDISYNTH 

Microsoft Vanilla driver MIDI synthsizer. 
MM_MSFT_GENERIC_AUX_LINE 

Microsoft Vanilla driver auxiliary line input. 
MM_MSFT_GENERIC_AUX_MIC 

Microsoft Vanilla driver auxiliary microphone. 
MM_MSFT_GENERIC_AUX_CD 

Microsoft Vanilla driver auxiliary CD. 
MM_MSFT_WSS_OEM_MIXER 

Microsoft OEM Audio Board mixer driver. 
MM_MSFT_MSACM 

Microsoft Audio Compression Manager. 
MM_MSFT_ACM_MSADPCM 

Microsoft ADPCM Codec. 
MM_MSFT_ACM_IMAADPCM 

IMA ADPCM Codec. 
MM_MSFT_ACM_MSFILTER 

Microsoft Filter. 
MM_MSFT_ACM_GSM610 

GSM 610 Codec. 
MM_MSFT_ACM_G711 

G.711 Codec. 
MM_MSFT_ACM_PCM 

PCM Converter. 
MM_WSS_SB16_WAVEIN 

Sound Blaster 16 waveform input. 
MM_WSS_SB16_WAVEOUT 

Sound Blaster 16 waveform output. 
MM_WSS_SB16_MIDIIN 

Sound Blaster 16 MIDI input. 
MM_WSS_SB16_MIDIOUT 

Sound Blaster 16 MIDI output. 
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MM_WSS_SB16_SYNTH 

Sound Blaster 16 FM synthesizer. 
MM_WSS_SB16_AUX_LINE 

Sound Blaster 16 auxiliary line input. 
MM_WSS_SB16_AUX_CD 

Sound Blaster 16 auxiliary CD. 
MM_WSS_SB16_MIXER 

Sound Blaster 16 mixer device. 
MM_WSS_SBPRO_WAVEIN 

Sound Blaster Pro waveform input. 
MM_WSS_SBPRO_WAVEOUT 

Sound Blaster Pro waveform output. 
MM_WSS_SBPRO_MIDIIN 

Sound Blaster Pro MIDI input. 
MM_WSS_SBPRO_MIDIOUT 

Sound Blaster Pro MIDI output. 
MM_WSS_SBPRO_SYNTH 

Sound Blaster Pro FM synthesizer. 
MM_WSS_SBPRO_AUX_LINE 

Sound Blaster Pro auxiliary line input. 
MM_WSS_SBPRO_AUX_CD 

Sound Blaster Pro auxiliary CD. 
MM_WSS_SBPRO_MIXER 

Sound Blaster Pro mixer. 
MM_MSFT_WSS_NT_WAVEIN 

WSS NT waveform input. 
MM_MSFT_WSS_NT_WAVEOUT 

WSS NT waveform output. 
MM_MSFT_WSS_NT_FMSYNTH_STEREO 

WSS NT FM synthesizer. 
MM_MSFT_WSS_NT_MIXER 

WSS NT mixer. 
MM_MSFT_WSS_NT_AUX 

WSS NT auxiliary. 
MM_MSFT_SB16_WAVEIN 

Sound Blaster 16 waveform input. 
MM_MSFT_SB16_WAVEOUT 

Sound Blaster 16 waveform output. 
MM_MSFT_SB16_MIDIIN 

Sound Blaster 16 MIDI input. 
MM_MSFT_SB16_MIDIOUT 

Sound Blaster 16 MIDI output. 
MM_MSFT_SB16_SYNTH 
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Sound Blaster 16 FM synthesizer. 
MM_MSFT_SB16_AUX_LINE 

Sound Blaster 16 auxiliary line input. 
MM_MSFT_SB16_AUX_CD 

Sound Blaster 16 auxiliary CD. 
MM_MSFT_SB16_MIXER 

Sound Blaster 16 mixer device. 
MM_MSFT_SBPRO_WAVEIN 

Sound Blaster Pro waveform input. 
MM_MSFT_SBPRO_WAVEOUT 

Sound Blaster Pro waveform output. 
MM_MSFT_SBPRO_MIDIIN 

Sound Blaster Pro MIDI input. 
MM_MSFT_SBPRO_MIDIOUT 

Sound Blaster Pro MIDI output. 
MM_MSFT_SBPRO_SYNTH 

Sound Blaster Pro FM synthesizer. 
MM_MSFT_SBPRO_AUX_LINE 

Sound Blaster Pro auxiliary line input. 
MM_MSFT_SBPRO_AUX_CD 

Sound Blaster Pro auxiliary CD. 
MM_MSFT_SBPRO_MIXER 

Sound Blaster Pro mixer. 
MM_MSFT_MSOPL_SYNTH 

Yamaha OPL2/OPL3-compatible FM synthesizer. 

e MOSCOM Corporation (MM_MOSCOM) Product IDs: 

MM_MOSCOM_VPC2400 


MOSCOM Four Point Voice Processing / Voice Recognition Board. 


e NCR Corporation (MM_NCR) Product IDs: 
MM_NCR_BA_WAVEIN 
BA waveform input. 
MM_NCR_BA_WAVEOUT 
BA waveform output. 
MM_NCR_BA_SYNTH 
BA synthesizer. 
MM_NCR_BA_AUX 
BA auxiliary. 
MM_NCR_BA_MIXER 
BA mixer. 
e New Media Corporation (MM_NEWMEDIA) Product IDs: 
MM_NEWMEDIA_WAVJAMMER 
New Media Jammer waveform. 
e Olivetti (MM_OLIVETTD Product IDs: 
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MM_OLIVETTI_WAVEIN 
Olivetti waveform input. 
MM_OLIVETTI_WAVEOUT 
Olivetti waveform output. 
MM_OLIVETTI_MIXER 
Olivetti mixer. 
MM_OLIVETTI_AUX 
Olivetti auxiliary. 
MM_OLIVETTI_MIDIIN 
Olivetti MIDI input. 
MM_OLIVETTI_MIDIOUT 
Olivetti MIDI output. 
MM_OLIVETTI_LSYNTH 
Olivetti synthesizer. 
MM_OLIVETTI_JOYSTICK 
Olivetti joystick. 
MM_OLIVETTI_ACM_GSM 
Olivetti ACM GSM. 
MM_OLIVETTI_LACM_ADPCM 
Olivetto ACM ADPCM. 
MM_OLIVETTI_LACM_SBC 
Olivetti ACM SBC. 
MM_OLIVETTI_ACM_OPR 
Olivetti ACM OPR. 
e OPTi Computers, Inc. (MM_OPTI) Product IDs: 
MM_OPTI_M16_FMSYNTH_STEREO 
M16 FM stereo synthesizer. 
MM_OPTI_M16_MIDIIN 
M16 MIDI input. 
MM_OPTI_M16_MIDIOUT 
M16 MIDI output. 
MM_OPTI_M16_WAVEIN 
M16 waveform input. 
MM_OPTI_M16_WAVEOUT 
M16 waveform output. 
MM_OPTI_M16_MIXER 
M16 mixer. 
MM_OPTI_M16_AUX 
M16 auxiliary. 
MM_OPTI_M32_WAVEIN 
M32 waveform input. 
MM_OPTI_M32_WAVEOUT 
M32 waveform output. 
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MM_OPTI_M32_MIDIIN 

M32 MIDI input. 
MM_OPTI_M32_MIDIOUT 

M32 MIDI output. 
MM_OPTI_M32_SYNTH_STEREO 

M32 stereo synthesizer. 
MM_OPTI_M32_MIXER 

M32 mixer. 
MM_OPTI_M32_AUX 

M32 auxiliary. 
MM_OPTI_P16_FMSYNTH_STEREO 

P16 FM stereo synthesizer. 
MM_OPTI_P16_MIDIIN 

P16 MIDI input. 
MM_OPTI_P16_MIDIOUT 

P16 MIDI output. 
MM_OPTI_P16_WAVEIN 

P16 waveform input. 
MM_OPTI_P16_WAVEOUT 

P16 waveform output. 
MM_OPTI_P16_MIXER 

P16 mixer. 
MM_OPTI_P16_AUX 

P16 auxiliary. 

e Roland (MM_ROLAND) Product IDs: 

MM_ROLAND_MPU401_MIDIOUT 

MPU401 MIDI output. 
MM_ROLAND_MPU401_MIDIIN 

MPU401 MIDI input. 
MM_ROLAND_SC7_MIDIOUT 

SC7 MIDI output. 
MM_ROLAND_SC7_MIDIIN 

SC7 MIDI input. 
MM_ROLAND_SERIAL_MIDIOUT 

Serial MIDI output. 
MM_ROLAND_SERIAL_MIDIIN 

Serial MIDI input. 
MM_ROLAND_SMPU_MIDIOUTA 

SMPU MIDI output A. 
MM_ROLAND_SMPU_MIDIOUTB 

SMPU MIDI output B. 
MM_ROLAND_SMPU_MIDIINA 

SMPU MIDI input A. 


http://216.26.168.92/vbapi/ref/other/productids.html (15 of 26) [9/1/2002 6:19:18 PM] 


Windows API Guide: Product Identifiers 


MM_ROLAND_SMPU_MIDIINB 
SMPU MIDI input B. 
e Sierra Semiconductor Corp. (MM_SIERRA) Product IDs: 
MM_SIERRA_ARIA_MIDIOUT 
Aria MIDI output. 
MM_SIERRA_ARIA_MIDIIN 
Aria MIDI input. 
MM_SIERRA_ARIA_SYNTH 
Aria synthesizer. 
MM_SIERRA_ARIA_WAVEOUT 
Aria waveform output. 
MM_SIERRA_ARIA_WAVEIN 
Aria waveform input. 
MM_SIERRA_ARIA_AUX 
Aria auxiliary. 
MM_SIERRA_ARIA_AUX2 
Aria auxiliary 2. 
e Silicon Soft, Inc. (MM_SILICONSOFT) Product IDs: 
MM_SILICONSOFT_SC1_WAVEIN 
High-sample-rate waveform input. 
MM_SILICONSOFT_SC1_WAVEOUT 
High-sample-rate waveform output. 
MM_SILICONSOFT_SC2_WAVEIN 
High-sample-rate, two-channel waveform input. 
MM_SILICONSOFT_SC2_WAVEOUT 
High-sample-rate, two-channel waveform output. 
MM_SILICONSOFT_SOUNDJR2_WAVEOUT 
Self-powered waveform output. 
MM_SILICONSOFT_SOUNDJR2PR_WAVEIN 
Self-powered waveform input. 
MM_SILICONSOFT_SOUNDJR2PR_WAVEOUT 
Self-powered, two-channel waveform output. 
MM_SILICONSOFT_SOUNDJR3_WAVEIN 
Self-powered, two-channel waveform input. 
e Tandy Corporation (MM_TANDY) Product IDs: 
MM_TANDY_VISWAVEIN 
VIS waveform input. 
MM_TANDY_VISWAVEOUT 
VIS waveform output. 
MM_TANDY_VISBIOSSYNTH 
VIS BIOS synthesizer. 
MM_TANDY_SENS_MMAWAVEIN 
SENS MMA waveform input. 
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MM_TANDY_SENS_MMAWAVEOUT 
SENS MMA waveform output. 
MM_TANDY_SENS_MMAMIDIIN 
SENS MMA MIDI input. 
MM_TANDY_SENS_MMAMIDIOUT 
SENS MMA MIDI output. 
MM_TANDY_SENS_VISWAVEOUT 
SENS VIS waveform output. 
MM_TANDY_PSSJWAVEIN 
PSSJ waveform input. 
MM_TANDY_PSSJWAVEOUT 
PSSJ waveform output. 
e Truevision (MM_TRUEVISION) Product IDs: 
MM_TRUEVISION_WAVEIN1 
Truevision waveform input. 
MM_TRUEVISION_WAVEOUT1 
Truevision waveform output. 
e Videologic (MM_VIDEOLOGIC) Product IDs: 
MM_VIDEOLOGIC_MSWAVEIN 
Videologic waveform input. 
MM_VIDEOLOGIC_MSWAVEOUT 
Videologic waveform output. 
e Vitec Multimedia (MM_VITEC) Product IDs: 
MM_VITEC_VMAKER 
Vitec VMaker. 
MM_VITEC_VMPRO 
Vitec VMaker Pro. 
e Vocaltec Ltd. (MM_VOCALTEC) Product IDs: 
MM_VOCALTEC_WAVEOUT 
Vocaltec waveform output. 
MM_VOCALTEC_WAVEIN 
Vocaltec waveform input. 
e Wang Laboratories, Inc. (MM_WANGLABS) Product IDs: 
MM_WANGLABS_WAVEIN1 
Wang Laboratories waveform input. 
MM_WANGLABS_WAVEOUT1 
Wang Laboratories waveform output. 
e Winnov, Inc. (MM_WINNOV) Product IDs: 
MM_WINNOV_CAVIAR_WAVEIN 
Caviar waveform input. 
MM_WINNOV_CAVIAR_WAVEOUT 
Caviar waveform output. 
MM_WINNOV_CAVIAR_VIDC 
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Caviar VIDC. 
MM_WINNOV_CAVIAR_CHAMPAGNE 

Caviar Fourcc Champagne. 
MM_WINNOV_CAVIAR_YUV8 

Caviar Fourcc YUV8. 

e Yamaha Corporation of America (MM_YAMAHA) Product IDs: 

MM_YAMAHA_GSS_SYNTH 

GSS synthesizer. 
MM_YAMAHA_GSS_WAVEOUT 

GSS waveform output. 
MM_YAMAHA_GSS_WAVEIN 

GSS waveform input. 
MM_YAMAHA_GSS_MIDIOUT 

GSS MIDI output. 
MM_YAMAHA_GSS_MIDIIN 

GSS MIDI input. 
MM_YAMAHA_GSS_AUX 

GSS auxiliary. 


Constant Definitions 











Const MM_APT_ACE100CD = 1 

Const MM_ARTISOFT_SBWAVEIN = 1 
Const MM_ARTISOFT_SBWAVEOUT = 2 
Const MM _AZTECH_AUX_CD = 401 

Const MM_AZTECH_AUX_LINE = 402 
Const MM_AZTECH_AUX_MIC = 403 
Const MM_AZTECH_AUX = 404 

Const MM _AZTECH_DSP16_WAVEIN = 65 
Const MM _AZTECH_DSP16_WAVEOUT = 66 
Const MM_AZTECH_DSP16_FMSYNTH = 68 
Const MM_AZTECH_DSP16_WAVESYNTH = 70 
Const MM_AZTECH_NOVA16_WAVEIN = 71 
Const MM_AZTECH_NOVA16_WAVEOUT = 72 
Const MM _AZTECH_NOVA16_MIXER = 73 
Const MM_AZTECH_PRO16_WAVEIN = 33 
Const MM _AZTECH_PRO16_WAVEOUT = 34 
Const MM_AZTECH_WASH16_WAVEIN = 74 
Const MM_AZTECH_WASH16_WAVOUT = 75 
Const MM_AZTECH_WASH16_MIXER = 76 
Const MM_AZTECH_MIDIOUT = 3 

Const MM _AZTECH_MIDIIN = 4 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


MM_CREATIVE_A 
MM_CREATIVE_A 
MM_CREATIVE_A 
MM_CREATIVE_A 
MM_CREATIVE_A 
MM_CREATIVE_A 
MM_CREATIVE_A 








MM_ECHO_SYNTH 


MM_ECHO_AUX = 


MM_ESS_AMAUX 

















MM_ESS_AMSYNTH 
MM_ESS_AMMIDIOUT = &H5 


MM_AZTECH_WAVEIN = 17 
MM_AZTECH_WAVEOUT 
MM AZTECH_FMSYNTH = 20 
MM_ AZTECH_MIXER = 21 

MM_CAT_WAVEOUT 


18 


= 1 


X_CD = 401 


X_LINE = 


X_MIC = 


X_MASTER 


X_PCSPK 


X_WAVE = 
X_MIDI = 
MM_CREATIVE_SB15_WAVEIN 
MM_CREATIVE_SB15_WAVEOUT = 101 
MM_CREATIVE_SB16_MIXER 
MM_CREATIVE_SB20_WAVEIN = 2 
MM_CREATIVE_SB20_WAVEOUT = 102 
MM_CREATIVE_SBP16_WAVEIN = 4 
MM_CREATIVE_SBP16_WAVEOUT = 104 
MM_CREATIVE_SBPRO_WAVEIN = 3 
MM_CREATIVE_SBPRO_WAVEOUT = 103 
MM_CREATIVE_SBPRO_MIXER 
MM_CREATIVE_MIDIOUT = 
MM_CREATIVE_MIDIIN = 202 
MM_CREATIVE_FMSYNTH_MONO = 301 
MM_CREATIVE_FMSYNTH_STEREO = 302 
MM_CREATIVE_MIDI_AWE32 
MM_DSP_GROUP_TRUESPEECH 
MM_DSP_SOLUTIONS_WAVEOUT = 1 
MM_DSP_SOLUTIONS_WAVEIN 
MM_DSP_SOLUTIONS_SYNTH 
MM_DSP_SOLUTIONS_AUX 


= &H1 


MM_ECHO_WAVEOUT = &H2 
MM_ECHO_WAVEIN 
MM_ECHO_MIDIOUT = &H4 
MM_ECHO_MIDIIN 


= &H3 


= SHS 
&H6 


MM_ESS_AMWAVEOUT = &H1 
MM_ESS_AMWAVEIN = &H2 


&H3 
= &H4 








402 


403 


= 404 
405 
406 
407 
= 1 


= 409 


= 408 


201 


= 303 
= &H1 


= 2 
= 3 
4 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


MM_ESS_AMMIDIIN = &H6 




















MM_ESS_AUX_CD = &H8 
MM_ESS_ES488_WAVEOUT = &H10 
MM_ESS_ES488_WAVEIN = &H11 
MM_ESS_ES488_MIXER = &H12 
MM_ESS_ES688_WAVEOUT = &H13 
MM _ESS_ES688_WAVEIN = &H14 
MM_ESS_ES688_MIXER = &H15 
MM _ESS_ES1488_WAVEOUT = &H16 
MM_ESS_ES1488_ WAVEIN = &H17 
MM_ESS_ES1488_ MIXER = &H18 
MM _ESS_ES1688_WAVEOUT = &H19 
MM_ESS_ES1688_WAVEIN = &H1A 
MM_ESS_ES1688_MIXER = &H1B 
MM_ESS_MPU401_MIDIOUT = &H9 
MM_ ESS_MPU401_MIDIIN = &HA 
MM_ESS_MIXER = &H7 
MM_EVEREX_CARRIER = &H1 

MM _ IBM PCMCIA_WAVEIN = 11 
MM_ IBM PCMCIA_WAVEOUT = 12 
MM _ IBM PCMCIA_SYNTH = 13 
MM_IBM_PCMCIA_MIDIIN = 14 
MM_IBM_PCMCIA_MIDIOUT = 15 
MM _ IBM PCMCIA_AUX = 1 





6 
MM MMOTION_WAVEAUX = 1 
MM MMOTION_WAVEOUT = 2 
MM MMOTION_WAVEIN = 3 
MM_ICS_WAVEDECK_WAVEOUT = 1 
MM_ICS_WAVEDECK_WAVEIN = 2 





MM_ICS_WAVEDECK_MIXER = 3 
MM_ICS_WAVEDECK_AUX = 4 
MM_ICS_WAVEDECK_SYNTH = 5 

MM _INTERACTIVE_WAVEIN = &H45 
MM_INTERACTIVE_WAVEOUT = &H45 


MM _TOMAGIC_TEMPO_WAVEOUT = 1 
MM _ITOMAGIC_TEMPO_WAVEIN = 2 
MM TOMAGIC_TEMPO_SYNTH = 3 
MM _TOMAGIC_TEMPO_MIDIOUT = 4 
MM _TOMAGIC_TEMPO_MXDOUT = 5 
MM _TOMAGIC_TEMPO_AUXOUT = 6 
MM _ITERATED_SYS_FUFCODEC = 1 
MM _KORG_PCIF_MIDIOUT = 1 

MM _KORG_PCIF_MIDIIN = 2 
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Const MM_LYRRUS_ BRIDGE GUITAR = 1 
Const MM MATSUSHITA WAVEIN = 1 
Const MM MATSUSHITA _WAVEOUT = 2 
Const MM _MATSUSHITA_FMSYNTH_STEREO = 3 
Const MM MATSUSHITA MIXER = 4 
Const MM MATSUSHITA AUX = 5 

Const MM _CDPC_MIDIOUT = &H71 
Const MM_CDPC_MIDIIN = &H72 

Const MM_CDPC_SYNTH = &H73 

Const MM _CDPC_WAVEOUT = &H74 
Const MM _CDPC_WAVEIN = &H75 

Const MM_CDPC_MIXER = &H76 

Const. MM “CDPC AUX = &H77 

Const MM_OPUS1208_MIDIOUT = &H81 
Const MM_OPUS1208_MIDIIN = &H82 
Const MM_OPUS1208_SYNTH = &H83 
Const MM_OPUS1208_ WAVEOUT = &H84 
Const MM_OPUS1208_WAVEIN = &H85 
Const MM_OPUS1208_MIXER = &H86 
Const MM_OPUS1208_AUX = &H87 
Const MM_OPUS1216_MIDIOUT = &H91 
Const MM_OPUS1216_MIDIIN = &H92 
Const MM_OPUS1216_SYNTH = &H93 
Const MM_OPUS1216_WAVEOUT = &H94 
Const MM_OPUS1216_WAVEIN = &H95 
Const MM_OPUS1216_MIXER = &H96 
Const MM_OPUS1216_AUX = &H97 
Const MM _PROAUD_MIDIOUT = &H11 
Const MM _PROAUD_MIDIIN = &H12 
Const MM _PROAUD_SYNTH = &H13 
Const MM _PROAUD_WAVEOUT = &H14 
Const MM PROAUD_WAVEIN = &H15 
Const MM _PROAUD_MIXER = &H16 
Const MM _PROAUD_AUX = &H17 

Const MM _PROAUD_16 MIDIOUT = &H61 
Const MM _PROAUD_16_MIDIIN = &H62 
Const MM _PROAUD_16_ SYNTH = &H63 
Const MM _PROAUD_16 WAVEOUT = &H64 
Const MM _PROAUD_16_WAVEIN = &H65 
Const MM _PROAUD_16_MIXER = &H66 
Const MM _PROAUD_16_AUX = &H67 
Const MM _PROAUD_PLUS_MIDIOUT = &H51 
Const MM _PROAUD_PLUS_MIDIIN = &H52 
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Const MM_PROAUD_PLUS_SYNTH = &H53 
Const MM_PROAUD_PLUS_WAVEOUT = &H54 
Const MM _PROAUD_PLUS_WAVEIN = &H55 
Const MM_PROAUD_PLUS_MIXER = &H56 
Const MM_PROAUD_PLUS_AUX = &H57 
Const MM_STUDIO_16_MIDIOUT = &H61 
Const MM_STUDIO_16_MIDIIN = &H62 
Const MM STUDIO 16 SYNIB = &H63 
Const MM_STUDIO_16_WAVEOUT = &H64 
Const MM_STUDIO_16_WAVEIN = &H65 
Const MM_STUDIO_16_MIXER = &H66 
Const MM_STUDIO_16_AUX = &H67 
Const MM_THUNDER_SYNTH = &H23 
Const MM_THUNDER_WAVEOUT = &H24 
Const MM_THUNDER_WAVEIN = &H25 
Const MM_THUNDER_AUX = &H27 

Const MM_TPORT_WAVEOUT = &H41 
Const MM_TPORT_WAVEIN = &H42 
Const MM_TPORT_SYNTH = &H43 

Const MM _MELABS_MIDI2GO = &H1 
Const MM _METHEUS_ZIPPER = 1 

Const MM_MIDI_MAPPER = 1 

Const MM _WAVE_MAPPER = 2 

Const MM_SNDBLST_MIDIOUT = 3 
































Const MM_SNDBLST_MIDIIN = 4 
Const MM_SNDBLST_SYNTH = 5 
Const MM_SNDBLST_WAVEOUT = 6 

















Const MM _SNDBLST_WAVEIN = 7 

Const MM_ADLIB = 9 

Const MM_MPU401_MIDIOUT = 10 

Const MM _MPU401_MIDIIN = 11 

Const MM_PC_JOYSTICK = 12 

Const MM _PCSPEAKER_WAVEOUT = 13 

Const MM MSFT _WSS_WAVEIN = 14 

Const MM_MSFT_WSS_WAVEOUT = 15 

Const MM_MSFT_WSS_FMSYNTH_STEREO = 16 
Const MM MSFT _WSS_MIXER = 17 

Const MM_MSFT_WSS_OEM WAVEIN = 18 
Const MM MSFT _WSS_OEM WAVEOUT = 19 
Const MM _ MSFT _WSS_OEM FMSYNTH_STEREO = 20 
Const MM_ MSFT WSS _AUX = 21 

Const MM_ MSFT _WSS_OEM AUX = 22 

Const MM_MSFT_GENERIC_WAVEIN = 23 
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Const MM_MSFT_GENERIC_WAVEOUT = 24 
Const MM_MSFT_GENERIC_MIDIIN = 25 
Const MM _MSFT_GENERIC_MIDIOUT = 26 
Const MM MSFT _GENERIC_MIDISYNTH = 27 
Const MM_MSFT_GENERIC_AUX_LINE = 28 
Const MM_MSFT_GENERIC_AUX_MIC = 29 
Const MM_ MSFT GENERIC _AUX_CD = 30 
Const MM_MSFT_WSS_OEM MIXER = 31 
Const MM _MSFT_MSACM = 32 

Const MM_MSFT_ ACM MSADPCM = 33 
Const MM_MSFT_ ACM _IMAADPCM = 34 
Const MM_MSFT_ ACM MSFILTER = 35 
Const MM _MSFT_ACM GSM610 = 36 
Const MM_MSFT_ACM_G711 = 37 

Const MM_MSFT_ ACM PCM = 38 

Const MM_WSS_SB16_WAVEIN = 39 
Const MM_WSS_SB16_WAVEOUT = 40 
Const MM_WSS_SB16_MIDIIN = 41 
Const MM_WSS_SB16_MIDIOUT = 42 
Const MM_WSS_SB16_SYNTH = 43 

Const MM_WSS_SB16_AUX_LINE = 44 
Const MM_WSS_SB16_AUX_CD = 45 
Const MM_WSS_SB16_MIXER = 46 

Const MM WSS _SBPRO_WAVEIN = 47 
Const MM_WSS_SBPRO_WAVEOUT = 48 
Const MM_WSS_SBPRO_MIDIIN = 49 
Const MM_WSS_SBPRO_MIDIOUT = 50 
Const MM_WSS_SBPRO_SYNTH = 51 
Const MM_WSS_SBPRO_AUX_LINE = 52 
Const MM_WSS_SBPRO_AUX_CD = 53 
Const MM WSS _SBPRO_MIXER = 54 
Const MM MSFT _WSS_NT_WAVEIN = 55 
Const MM_MSFT_WSS_NT_WAVEOUT = 56 
Const MM MSFT _WSS_NT_FMSYNTH_STEREO = 57 
Const MM_MSFT_WSS_NT_MIXER = 58 
Const MM_MSFT_WSS_NT_AUX = 59 
Const MM_MSFT_SB16_WAVEIN = 60 
Const MM_MSFT_SB16_WAVEOUT = 61 
Const MM MSFT _SB16_MIDIIN = 62 
Const MM_MSFT_SB16_MIDIOUT = 63 
Const MM _MSFT_SB16_SYNTH = 64 
Const MM_MSFT_SB16_AUX_LINE = 65 
Const MM MSFT _SB16_AUX_CD = 66 
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Const MM _MSFT_SB16_ MIXER = 67 
Const MM_MSFT_SBPRO_WAVEIN = 68 
Const MM_MSFT_SBPRO_WAVEOUT = 69 
Const MM_MSFT_SBPRO_MIDIIN = 70 
Const MM MSFT SBPRO_MIDIOUT = 71 
Const MM_MSFT_SBPRO_SYNTH = 72 
Const MM_MSFT_SBPRO_AUX_LINE = 73 
Const MM MSFT SBPRO_AUX_CD = 74 
Const MM MSFT SBPRO_MIXER = 75 
Const MM MSFT _MSOPL SYNTH = 76 
Const MM _MOSCOM_VPC2400 = 1 
Const MM _NCR_BA WAVEIN = 1 

Const MM _NCR_BA WAVEOUT = 2 


Const MM _NCR_BA_ SYNTH = 3 
Const MM_NCR_BA_ AUX = 4 
Const MM_NCR_BA_ MIXER = 5 








Const MM_NEWMEDTA WAVJAMMER = 1 





Const MM_OLIVETTI_WAVEIN = 1 
Const MM_OLIVETTI_WAVEOUT = 2 
Const MM_OLIVETTI_MIXER = 3 
Const MM_OLIVETTI_AUX = 4 
Const MM_OLIVETTI_MIDIIN = 5 
Const MM _OLIVETTI_MIDIOUT = 6 
Const MM OLIVE TTI SYNTH = 7 
Const MM_OLIVETTI_JOYSTICK = 8 
Const MM_OLIVETTI_ACM_GSM = 9 
Const MM_OLIVETTI_ACM_ADPCM = 10 
Const MM_OLIVETTI_ACM_SBC = 12 
Const MM_OLIVETTI_ACM_OPR = 13 





Const MM_OPTI_M16_FMSYNTH_STEREO = &H1 
Const MM_OPTI_M16_MIDIIN = &H2 

Const MM_OPTI_M16_MIDIOUT = &H3 

Const MM_OPTI_M16_WAVEIN = &H4 

Const MM_OPTI_M16_WAVEOUT = &H5 

Const MM_OPTI_M16_MIXER = &H6 

Const MM_OPTI_M16_AUX = &H7 

Const MM_OPTI_M32_WAVEIN = &H20 

Const MM_OPTI_M32_WAVEOUT = &H21 
Const MM_OPTI_M32_MIDIIN = &H22 

Const MM_OPTI_M32_MIDIOUT = &H23 
Const MM_OPTI_M32_SYNTH_STEREO = &H24 
Const MM_OPTI_M32_MIXER = &H25 

Const MM_OPTI_M32_AUX = &H26 
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Const MM_OPTI_P16_FMSYNTH_STEREO = &H10 
Const MM_OPTI_P16_MIDIIN = &H11 

Const MM_OPTI_P16_MIDIOUT = &H12 

Const MM_OPTI_P16_WAVEIN = &H13 

Const MM_OPTI_P16_WAVEOUT = &H14 

Const MM_OPTI_P16_MIXER = &H15 

Const MM_OPTI_P16_AUX = &H16 

Const MM_ROLAND_MPU401_MIDIOUT = 15 
Const MM_ROLAND_MPU401_MIDIIN = 16 
Const MM_ROLAND_SC7_MIDIOUT = 21 

Const MM_ROLAND_SC7_MIDIIN = 22 

Const MM_ROLAND_SERIAL MIDIOUT = 23 
Const MM_ROLAND_SERIAL MIDIIN = 24 
Const MM_ROLAND_SMPU_MIDIOUTA = 17 
Const MM_ROLAND_SMPU_MIDIOUTB = 18 
Const MM_ROLAND_SMPU_MIDIINA = 19 

Const MM_ROLAND_SMPU_MIDIINB = 20 

Const MM _ SIERRA_ARIA_MIDIOUT &H14 
Const MM_SIERRA_ARIA MIDIIN = &H15 
Const MM_SITERRA_ARIA_ SYNTH = &H16 

Const MM_STERRA_ARIA_WAVEOUT = &H17 
Const MM_STERRA_ARIA _WAVEIN = &H18 
Const MM_SITERRA_ARIA_AUX = &H19 

Const MM_SIERRA_ARIA_AUX2 = &H20 

Const MM_SILICONSOFT_SC1_WAVEIN = 1 
Const MM_SILICONSOFT_SC1_WAVEOUT = 2 
Const MM_SILICONSOFT_SC2_WAVEIN = 3 
Const MM_SILICONSOFT_SC2_WAVEOUT = 4 
Const MM_SILICONSOFT_SOUNDJR2_WAVEOUT = 5 
Const MM_SILICONSOFT_SOUNDJR2PR_WAVEIN = 
Const MM_SILICONSOFT_SOUNDJR2PR_WAVEOUT = 
Const MM_SILICONSOFT_SOUNDJR3_WAVEIN = 8 
Const MM_TANDY_VISWAVEIN = 1 

Const MM_TANDY_VISWAVEOUT = 2 

Const MM_TANDY_VISBIOSSYNTH = 3 

Const MM_TANDY_SENS_MMAWAVEIN = 4 

Const MM_TANDY_SENS_MMAWAVEOUT = 5 
Const MM_TANDY_SENS_MMAMIDIIN = 6 

Const MM_TANDY_SENS_MMAMIDIOUT = 7 
Const MM_TANDY_SENS_VISWAVEOUT = 8 
Const MM_TANDY_PSSJWAVEIN = 9 

Const MM_TANDY_PSSJWAVEOUT = 10 

Const MM_TRUEVISION_WAVEIN1 = 1 
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Const MM_TRUEVISION_WAVEOUTI1 = 2 
Const MM_VIDEOLOGIC_MSWAVEIN = 
Const MM _VIDEOLOGIC_MSWAVEOUT = 2 
Const MM_VITEC_VMAKER = 1 

Const MM _VITEC_VMPRO = 2 

Const MM_VOCALTEC_WAVEOUT = 1 

Const MM_VOCALTEC_WAVEIN = 2 

Const MM _WANGLABS_WAVEIN1 = 1 

Const MM _WANGLABS_WAVEOUTI1 = 2 

Const MM_WINNOV_CAVIAR_WAVEIN = 1 
Const MM_WINNOV_CAVIAR_WAVEOUT = 2 
Const MM _WINNOV_CAVIAR_VIDC = 3 
Const MM_WINNOV_CAVIAR_CHAMPAGNE = 4 
Const MM _WINNOV_CAVIAR_YUV8 = 5 
Const MM_YAMAHA GSS_SYNTH = &H1 
Const MM_YAMAHA GSS_WAVEOUT = &H2 
Const MM_YAMAHA GSS_WAVEIN = &H3 
Const MM_YAMAHA GSS_MIDIOUT = &H4 
Const MM_YAMAHA GSS_MIDIIN = &H5 
Const MM_YAMAHA GSS_AUX = &H6 


Used By 


AUXCAPS, JOYCAPS, WAVEOUTCAPS 


| 
| 




















Go back to the Other Information listing. 
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Virtual-Key Codes 


Description & Usage 


The virtual-key codes identify various virtual keys. Virtual keys mainly consist of actual keyboard keys, 
but also include "virtual" elements such as the three mouse buttons. The virtual keys also include many 
"keys" which usually do not exist at all! A key's virtual-key code does not change when modifier keys 
(Ctrl, Alt, Shift, etc.) are held -- e.g., the 1 key has the same virtual-key code whether 1 or ! is pressed. 
However, the numbers in the numeric keypad on the keyboard do have two different virtual-key codes: 
one for when Num Lock is on, and another for when Num Lock is off. Note that the virtual-key codes of 
0-9 and A-Z equal their ASCII codes. 


Note: The actual meanings of some of the key codes may vary on keyboards designed for different 
languages. Most notably, the VK_OEM_* that denote punctuation keys may vary between languages, 
relating to a different punctuation key. The meanings listed below are for a U.S. English-language 
keyboard. 


Virtual Key Codes 


VK_LBUTTON 

The left mouse button 
VK_RBUTTON 

The right mouse button 
VK_CANCEL 

The Cancel virtual key, used for control-break processing 
VK_MBUTTON 

The middle mouse button 
VK_BACK 

Backspace 
VK_TAB 

Tab 
VK_CLEAR 

5 (keypad without Num Lock) 
VK_RETURN 
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Enter 
VK_SHIFT 

Shift (either one) 
VK_CONTROL 

Ctrl (either one) 
VK_MENU 

Alt (either one) 
VK_PAUSE 

Pause 
VK_CAPITAL 

Caps Lock 
VK_ESCAPE 

Esc 
VK_SPACE 

Spacebar 
VK_PRIOR 

Page Up 
VK_NEXT 

Page Down 
VK_END 

End 
VK_HOME 

Home 
VK_LEFT 

Left Arrow 
VK_UP 

Up Arrow 
VK_RIGHT 

Right Arrow 
VK_DOWN 

Down Arrow 
VK_SELECT 

Select 
VK_PRINT 

Print (only used by Nokia keyboards) 
VK_EXECUTE 

Execute (not used) 
VK_SNAPSHOT 

Print Screen 
VK_INSERT 

Insert 
VK_DELETE 

Delete 
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VK_HELP 

Help 
VK_0 

0 
VK_1 

1 
VK_2 

2 
VK_3 

3 
VK_4 

4 
VK_5 

5 
VK_6 

6 
VK_7 

7 
VK_8 

8 
VK_9 

9 
VK_A 

A 
VK_B 

B 
VK_C 

C 
VK_D 

D 
VK_E 

E 
VK_F 

F 
VK_G 

G 
VK_H 

H 
VK_I 

I 
VK_J 

J 
VK_K 
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K 
VK_L 
i 
VK_M 
M 
VK_N 
N 
VK_O 
O 
VK_P 
P 
VK_Q 
Q 
VK_R 
R 
VK_S 
S 
VK_T 
T 
VK_U 
U 
VK_V 
V 
VK_W 
W 
VK_X 
X 
VK_Y 
Y 
VK_Z 
Z 
VK_STARTKEY 
Start Menu key 
VK_CONTEXTKEY 
Context Menu key 
VK_NUMPADO 
0 (keypad with Num Lock) 
VK_NUMPADI1 
1 (keypad with Num Lock) 
VK_NUMPAD2 
2 (keypad with Num Lock) 
VK_NUMPAD3 
3 (keypad with Num Lock) 
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VK_NUMPAD4 

4 (keypad with Num Lock) 
VK_NUMPADS 

5 (keypad with Num Lock) 
VK_NUMPAD6 

6 (keypad with Num Lock) 
VK_NUMPAD7 

7 (keypad with Num Lock) 
VK_NUMPAD8 

8 (keypad with Num Lock) 
VK_NUMPAD9 

9 (keypad with Num Lock) 
VK_MULTIPLY 

* (keypad) 
VK_ADD 

+ (keypad) 
VK_SEPARATER 

Separator (never generated by the keyboard) 
VK_DECIMAL 

. (keypad with Num Lock) 
VK_DIVIDE 

/ (keypad) 
VK_FI 

Fl 
VK_F2 

F2 
VK_F3 

F3 
VK_F4 

F4 
VK_F5 

F5 
VK_F6 

F6 
VK_F7 

F7 
VK_F8 

F8 
VK_F9 

F9 
VK_FI10 

F10 
VK_F11 
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F11 
VK_F12 

F12 
VK_F13 

F13 
VK_F14 

F14 
VK_F15 

F15 
VK_F16 

F16 
VK_F17 

F17 
VK_F18 

F18 
VK_F19 

F19 
VK_F20 

F20 
VK_F21 

F21 
VK_F22 

F22 
VK_F23 

F23 
VK_F24 

F24 
VK_NUMLOCK 

Num Lock 
VK_OEM_SCROLL 

Scroll Lock 
VK_OEM_1 


VK_OEM_PLUS 
VK_OEM_COMMA 
VK_OEM_MINUS 
VK_OEM_ PERIOD 


VK_OEM_2 
/ 
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VK_OEM_3 


VK_OEM_4 
ders 
oes 
T 


VK_OEM_8 

(unknown) 
VK_ICO_F17 

F17 on Olivetti extended keyboard (internal use only) 
VK_ICO_F18 

F18 on Olivetti extended keyboard (internal use only) 
VK_OEM_102 

< or | on IBM-compatible 102 enhanced non-U.S. keyboard 
VK_ICO_HELP 

Help on Olivetti extended keyboard (internal use only) 
VK_ICO_00 

00 on Olivetti extended keyboard (internal use only) 
VK_ICO_CLEAR 

Clear on Olivette extended keyboard (internal use only) 
VK_OEM_RESET 

Reset (Nokia keyboards only) 
VK_OEM_JUMP 

Jump (Nokia keyboards only) 
VK_OEM_PA1 

PA1 (Nokia keyboards only) 
VK_OEM_PA2 

PA2 (Nokia keyboards only) 
VK_OEM_PA3 

PA3 (Nokia keyboards only) 
VK_OEM_WSCTRL 

WSCTRL (Nokia keyboards only) 
VK_OEM_CUSEL 

CUSEL (Nokia keyboards only) 
VK_OEM_ATTN 

ATTN (Nokia keyboards only) 
VK_OEM_FINNISH 

FINNISH (Nokia keyboards only) 
VK_OEM_COPY 
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COPY (Nokia keyboards only) 
VK_OEM_AUTO 

AUTO (Nokia keyboards only) 
VK_OEM_ENLW 

ENLW (Nokia keyboards only) 
VK_OEM_BACKTAB 

BACKTAB (Nokia keyboards only) 
VK_ATTN 

ATTN 
VK_CRSEL 

CRSEL 
VK_EXSEL 

EXSEL 
VK_EREOF 

EREOF 
VK_PLAY 

PLAY 
VK_ZOOM 

ZOOM 
VK_NONAME 

NONAME 
VK_PA1 

PAI 
VK_OEM_CLEAR 

CLEAR 


Constant Definitions 


Const VK_LBUTTON & H1 
Const VK_RBUTTON = &H2 
Const VK_CANCEL = &H3 
Const VK_MBUTTON = &H4 
Const VK_BACK = &H8 
Const VK_TAB = &H9 
Const VK_CLEAR = &HC 
Const VK_RETURN = &HD 
Const VK_SHIFT = &H10 
Const VK_CONTROL = &H11 
Const VK_MENU = &H12 
Const VK_PAUSE = &H13 
Const VK_CAPITAL = &H14 
Const -VK ESCAPE = &H1B 
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Const VK_SPACE = &H20 
Const VK_PRIOR = &H21 
Const VK_NEXT = &H22 
Const VK_END = &H23 
Const VK_HOME = &H24 
Const VK_LEFT = &H25 
Const VK_UP = &H26 
Const VK_RIGHT = &H27 
Const VK_DOWN = &H28 
Const VK_SELECT = &H29 
Const VK_PRINT = &H2A 
Const VK_EXECUTE = &H2B 
Const VK_SNAPSHOT = &H2C 
Const VK_INSERT = &H2D 
Const VK_DELETE = &H2E 
Const VK_HELP = &H2F 
Const VK_O = &H30 
Const VK_1 = &H31 
Const VK_2 = &H32 
Const VK_3 = &H33 
Const VK_4 = &H34 
Const VK_5 = &H35 
Const VK_6 = &H36 
Const VK_7 = &H37 
Const VK_8 = &H38 
Const VK_9 = &H39 
Const VK_A = &H41 
Const VK_B = &H42 
Const VK_C = &H43 
Const VK_D = &H44 
Const VK_E = &H45 
Const VK_F = &H46 
Const VK_G = &H47 
Const VK_H = &H48 
Const VK_I = &H49 
Const VK_J = &H4A 
Const VK_K = &H4B 
Const VK_L = &H4C 
Const VK_M = &H4D 
Const VK_N = &H4E 
Const VK_O = &H4F 
Const VK_P = &H50 
Const VK_Q = &H5l1 
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Const VK_R = &H52 

Const VK_S = &H53 

Const VK_T = &H54 

Const VK_U = &H55 

Const VK_V = &H56 

Const VK_W = &H57 

Const VK_X = &H58 

Const VK_Y = &H59 

Const VK_Z = &H5A 

Const VK_STARTKEY = &H5B 
Const VK_CONTEXTKEY = &H5D 
Const VK_NUMPADO = &H60 
Const VK_NUMPADI1 = &H61 
Const VK_NUMPAD2 = &H62 
Const VK_NUMPAD3 = &H63 
Const VK_NUMPAD4 = &H64 
Const VK_NUMPAD5 = &H65 
Const VK_NUMPAD6 = &H66 
Const VK_NUMPAD7 = &H67 
Const VK_NUMPAD8 = &H68 
Const VK_NUMPAD9 = &H69 
Const VK_MULTIPLY = &H6A 
Const VK_ADD = &H6B 
Const VK_SEPARATOR = &H6C 
Const VK_SUBTRACT = &H6D 
Const VK_DECIMAL = &H6E 
Const VK_DIVIDE = &H6F 
Const VK_F1 &H70 

Const VK_F2 = &H71 

Const VK_F3 = &H72 

Const VK_F4 = &H73 

Const VK_F5 = &H74 

Const VK_F6 = &H75 

Const VK_F7 = &H76 

Const VK_F8 = &H77 

Const VK_F9 = &H78 

Const VK_F10 = &H79 
Const VK_F11 = &H7A 
Const VK_F12 = &H7B 
Const VK_F13 = &H7C 
Const VK_F14 = &H7D 
Const VK_F15 = &H7E 
Const VK_F16 = &H7F 
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Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 
Const 


VK_F17 = &H80 
VK_F18 &H81 
VK_F19 = &H82 
VK_F20 &H83 
VK_F21 = &H84 
VK_F22 &H85 
VK_F23 = &H86 
VK_F24 = &H87 
VK_NUMLOCK = 


VK_OEM_SCROLL = 


VK -OEM_ 1 


VR OEM: PLUS = 


= &HBA 


VK_OEM_COMMA = 
VK_OEM_MINUS = 
VK_OEM_PERIOD = 


VK_OEM_2 
VK_OEM_3 
VK_OEM_4 
VK_OEM_5 
VK_OEM_6 
VK_OEM_7 
VK_OEM_8 





VK_ICO_F17 = 
VK_ICO_F18 = 


& HBF 
= &HCO 
& HDB 
= &HDC 
& HDD 
= &HDE 

& HDF 


= &HE2 


&H90 


&HBB 


&HEO 
&HE1 


VK_OEM102 
VK_ICO_HELP = &HE3 
VK_ICO_00 = &HE4 
VK_ICO_CLEAR = &HE6 
VK_OEM_RESET = &HE9 
VK_OEM_JUMP = &HEA 
VK_OEM_PA1 = &HEB 
VK_OEM_PA2 & HEC 
VK_OEM_PA3 = &HED 
VK_OEM_WSCTRL = &HEE 
VK_OEM_CUSEL = &HEF 
VK_OEM_ATTN = &HFO 
VK_OEM_FINNISH = &HF1 
VR -OEM COPY. &HF2 
VK_OEM_AUTO = &HF3 
VK_OEM_ENLW &HF 4 
VK_OEM_BACKTAB = &HF5 
VK_ATIN = &HF6 
VK_CRSEL = &HF7 
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Const VK_EXSEL = &HF8 
Const VK_EREOF = &HF9 
Const VK_PLAY = &HFA 
Const VK_ZOOM = &HFB 
Const VK_NONAMF = &HFC 
Const VK_PA1 = &HFD 

Const VK_OEM CLEAR = &HFE 


Used By 


GetAsyncKeyState, GetKeyboardState, GetKeyState, keybd_event, KEYBDINPUT, SetKeyboardState 


Go back to the Other Information listing. 
Go back to the Reference section index. 
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Window Classes 


Window classes are sets of attributes shared by a group of windows. When a new window is created (for 
example, by CreateWindowEx), it inherits many of its properties from its class. One major use of classes 
is the creation of controls. Predefined window classes are essentially what makes controls such as buttons 
or edit boxes appear different from "normal" windows (although all windows belong to one class or 
another). 


Of course, you are not limited to using only the predefined classes. By calling RegisterClassEx your 
program can create its own window classes. However, for most purposes, using one of the predefined 
classes is best when creating some sort of control, especially if one already exists. 


Typically, a program uses these classes to create controls. Each class also has a unique set of window 
style flags that only apply to it. These unique styles typically control properties specific to that type of 
control. Below is a list of some of the window classes predefined in the Windows API. Note that this list 
does not (yet) include all classes defined in the Windows API. Information that applies to all window 
classes in general appears first in the list. 


e Styles Common to All Classes 
o Window styles shared by all classes NEW 


o Extended window styles shared by all classes NEW 
e Class-Specific Information 


o Button control (class "BUTTON") NEW 

o Combo Box control (class "COMBOBOX") NEW 
o Edit control (class "EDIT") NEW 

o IP Address control (class "SysIPAddress32") NEW 
o List Box control (class "LISTBOX") NEW 

o Scroll Bar control (class "SCROLLBAR") NEW 

o Static control (class "STATIC") NEW 


Back to the Reference section. 
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Base Window Styles 


The following window styles are shared by all windows, regardless of their class. They generally 
describe the window's general appearance, although many of the styles apply best to non-control 
windows (particularly overlapped windows). 


Styles 


WS_BORDER 
The window has a thin-line border. 
WS_CAPTION 
The window has a title bar. 
WS_CHILD, WS_CHILDWINDOW 
The window is a child window. These windows cannot have menu bars nor can have the 
WS_POPUP style. 
WS_CLIPCHILDREN 
For a parent window, exclude the areas occupied by child windows when drawing within the 
window (to avoid drawing on any child windows). 
WS_CLIPSIBLINGS 
For a child window, exclude the areas occupied by fellow children of the window's parent when 
drawing within the window (to avoid drawing on any sibling windows). 
WS_DISABLED 
The window is disabled. 
WS_DLGFRAME 
The window has a border style typical of dialog boxes. These windows cannot have a title bar. 
WS_GROUP 
Identifies the first control in a group of controls. Any controls following this one are assumed to 
be part of this control's group, until a control with the WS_GROUP style is encountered. 
WS_HSCROLL 
The window has a horizontal scroll bar. 
WS_MAXIMIZE 
The window is maximized. 
WS_MAXIMIZEBOX 
The window has a maximize button. This cannot be used on windows having the 
WS_EX_CONTEXTHELP extended window style. The WS_SY SMENU window style must also 
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be specified. 
WS_MINIMIZE, WS_ICONIC 
The window is minimized. 
WS_MINIMIZEBOX 
The window has a minimize button. This cannot be used on windows having the 


WS_EX_CONTEXTHELP extended window style. The WS_SYSMENU window style must also 


be specified. 
WS_OVERLAPPED, WS_TILED 
The window is an overlapped window, which as a title bar and a border. 
WS_OVERLAPPEDWINDOW, WS_TILEDWINDOW 
The window is an overlapped window, having a title bar, a sizing border, a title bar, a system 
menu, and minimize and maximize boxes. 
WS_POPUP 
The window is a popup window. This cannot be used with the WS_CHILD window style. 
WS_POPUPWINDOW 
The window is a popup window, having a thin-line border and system menu. The window can 
only be visible if it also has the WS_CAPTION window style. 
WS_SIZEBOX 
Same as WS_THICKFRAME. 
WS_SYSMENU 
The window has a system menu on its title bar. The WS_CAPTION window style must also be 
specified. 
WS_TABSTOP 
The control can press Tab repeatedly to set the focus to this control. 
WS_THICKFRAME 
The window has a sizing border. 
WS_VISIBLE 
The window is visible. 
WS_VSCROLL 
The window has a vertical scroll bar. 


Constant Definitions 


Const WS_BORDER = &H800000 

Const WS_CAPTION = &HC00000 

Const WS_CHILD = &H40000000 

Const WS_CHILDWINDOW = &H40000000 
Const WS_CLIPCHILDREN = &H2000000 
Const WS_CLIPSIBLINGS = &H4000000 
Const WS_DISABLED = &H8000000 
Const WS_DLGFRAME = &H400000 
Const WS_GROUP = &H20000 


http://216.26.168.92/vbapi/ref/other/classes/basestyles.html (2 of 3) [9/1/2002 6:20:43 PM] 


Windows API Guide: Base Window Styles 


Const WS_HSCROLL = &H100000 

Const WS_ICONIC = &H20000000 
Const WS_MAXIMIZE = &H1000000 
Const WS _MAXIMIZEBOX = &H10000 
Const WS_MINIMIZE = &H20000000 
Const WS_MINIMIZEBOX = &H20000 
Const WS_OVERLAPPED = &H0O 

Const WS_OVERLAPPEDWINDOW = &HCFOOOO 
Const WS_POPUP = &H80000000 

Const WS_POPUPWINDOW = &H80880000 
Const WS_SIZEBOX = &H40000 

Const WS_SYSMENU = &H80000 

Const WS_TABSTOP = &H10000 

Const WS_THICKFRAME = &H40000 
Const WS_TILED = &HO 

Const WS_TILEDWINDOW = &HCFOOOO 
Const WS_VISIBLE = &H10000000 
Const WS_VSCROLL = &H200000 


Back to the Window Classes list. 
Back to the Reference section. 
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Extended Window Styles 


Below is a list of the extended window styles. The main difference between these and regular window 
styles is that these are specified as a separate value. (For example, a call to CreateWindowEx takes one 
parameter for extended window styles and a second parameter for "regular" window styles.) These styles 
can be applied to any type of window, although many of them apply best to overlapped windows. 


Extended Styles 


WS_EX_ACCEPTFILES 

The window accepts files via a drag-and-drop operation. 
WS_EX_APPWINDOW 

The window also appears on the taskbar whenever it is visible. 
WS_EX_CLIENTEDGE 

The window has a border with a sunken edge. 
WS_EX_CONTEXTHELP 

A context-help button appears on the title bar. This cannot be used with the 

WS_MAXIMIZEBOX or WS_MINIMIZEBOX regular window styles. 
WS_EX_CONTROLPARENT 

The window contains children which can be TABbed through. 
WS_EX_DLGMODALFRAME 

The window has a modal dialog frame (a double border). 
WS_EX_LAYERED 

Windows 2000: The window is a layered window. 
WS_EX_LAYOUTRTL 

Windows 2000: The window's coordinate system places the horizontal origin on the right side, 

with increasing x values to the left and decreasing x values to the right. 
WS_EX_LEFT 

The window has generic left-aligned properties. 
WS_EX_LEFTSCROLLBAR 

If the language supports reading order alignment, position the vertical scroll bar (if any) to the left 

of the client area. 
WS_EX_LTRREADING 

Display window text using left-to-right reading. 
WS_EX_MDICHILD 
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The window is an MDI child window. 
WS_EX_NOACTIVATE 

Windows 2000: The window is never brought to the foreground as a result of direct user action. 
WS_EX_NOINHERITLA YOUT 

Windows 2000: Do not pass the window's layout to its child windows. 
WS_EX_NOPARENTNOTRIFY 

If the window is a child window, do not notify the parent window when the child window is 

created or destroyed. 
WS_EX_OVERLAPPEDWINDOW 

The window has the border of a typical overlapped window. 
WS_EX_PALETTEWINDOW 

The window is a topmost toolbar window with a raised edge, normally used for a floating palette. 
WS_EX_RIGHT 

The window has generic right-aligned properties, if the language supports reading order 

alignment. 
WS_EX_RIGHTSCROLLBAR 

Display the vertical scroll bar (if any) to the right of the client area. 
WS_EX_RTLREADING 

Display window text using right-to-left reading, if the language supports reading order alignment. 
WS_EX_STATICEDGE 

The window has a three-dimensional border intended for items which do not accept user input. 
WS_EX_TOOLWINDOW 

The window is designed to be a floating toolbar window, having a small title bar area. 
WS_EX_TOPMOST 

The window appears above all non-topmost windows, even if it is not active. 
WS_EX_TRANSPARENT 

The window appears transparent because its sibling windows below it are drawn first. 
WS_EX_WINDOWEDGE 

The window has a border with a raised edge. 


Constant Definitions 


Note: Some of the values of the extended window style flags are not listed. If you know their values, 
please e-mail me about them. 


Const WS_EX_ACCEPTFILES = &H10 
Const WS_EX_APPWINDOW = &H40000 
Const WS_EX_CLIENTEDGE = &H200 
Const WS_EX_CONTEXTHELP = &H400 
Const WS_EX_CONTROLPARENT = &H10000 
Const WS_EX_DLGMODALFRAME = &H1 

" Const WS_EX_LAYERED = ??? 
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' Const WS_EX_LAYOUTRTL = ??°? 

Const WS_EX_LEFT = &HO 

Const WS_EX_LEFTSCROLLBAR = &H4000 
Const WS_EX _LTRREADING = &H0O 

Const WS_EX_MDICHILD = &H40 

Const WS_EX_NOACTIVATE = &H8000000 
" Const WS_EX NOINHERITLAYOUT = ??°? 
Const WS_EX NOPARENTNOTIFY = &H4 
Const WS_EX _OVERLAPPEDWINDOW = &H300 
Const WS_EX PALETTEWINDOW = &H188 
Const WS_EX RIGHT = &H1000 

Const WS_EX RIGHTSCROLLBAR = &HO 
Const WS_EX _RTLREADING = &H2000 
Const WS_EX_STATICEDGE = &H20000 
Const WS_EX _TOOLWINDOW = &H80 

Const WS_EX_TOPMOST = &H8 

Const WS_EX_ TRANSPARENT = &H20 
Const WS_EX_WINDOWEDGE = &H100 


Back to the Window Classes list. 
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Button Control Window Class 


The button control's window class describes any type of button control. This includes command 
buttons, check boxes, and radio boxes. The button class style assigned to a button control determines 
what type of button it is. 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "BUTTON". 


Styles 


BS_3STATE 

The button is a check box which has three states: checked, grayed, and cleared. 
BS_AUTO3STATE 

The button is a check box which has three states: checked, grayed, and cleared. The button 

automatically changes its state when the user selects it. 
BS_AUTOCHECKBOX 

The button is a check box whose state toggles when the user selects it. 
BS_AUTORADIOBUTTON 

The button is a radio button whose state automatically changes to selected (and the state of all 

other radio buttons in the group to unselected) when the user selects it. 
BS_BITMAP 

The button displays a bitmap. 
BS_BOTTOM 

The button's text appears at the bottom of the button rectangle. 
BS_CENTER 

The button's text appears centered horizontally within the button rectangle. 
BS_CHECKBOX 

The button is a check box. 
BS_DEFPUSHBUTTON 

The button is the default push button in a dialog box, having a heavy black border. 
BS_GROUPBOX 

The window is a rectangular grouping frame in which other controls can be grouped. 
BS_FLAT 

The button is flat, not using the default 3D shading. 
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BS_ICON 
The button displays an icon. 
BS_LEFT 
The text in the button rectangle is left-justified. 
BS_LEFTTEXT, BS_RIGHTBUTTON 
The radio or check box's text appears to the left of the button instead of to the right. 
BS_MULTILINE 
The button's text is wrapped across multiple lines if it cannot fit on a single line. 
BS_NOTIFY 
The button sends focus notification messages to its parent window. 
BS_OWNERDRAW 
The owner of the window is responsible for manually drawing it whenever it needs to be redrawn. 
This window style cannot be combined with any other button styles. 
BS_PUSHBUTTON 
The button is a push button. 
BS_PUSHLIKE 
The radio or check button takes on the appearance of a push button. A checked state makes the 
button look depressed; a cleared state makes the button look normal. 
BS_RADIOBUTTON 
The button is a radio button. 
BS_RIGHT 
The text in the button rectangle is right-justified. 
BS_TEXT 
The button displays text. 
BS_TOP 
The text appears at the top of the button rectangle. 
BS_USERBUTTON 
Obsolete; use BS_OWNERDRAW instead. 
BS_VCENTER 
The text appears centered vertically within the button rectangle. 


Constant Definitions 


Const BS_3STATE = &H5 

Const BS_AUTO3STATE = &H6 
Const BS _AUTOCHECKBOX = &H3 
Const BS_AUTORADTIOBOX &H9 
Const BS_BITMAP = &H80 

Const BS_BOTTOM = &H800 
Const BS_CENTER = &H300 
Const BS_CHECKBOX = &H2 
Const BS_DEFPUSHBUTTON = &H1 
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Const BS_FLAT = &H8000 
Const BS_GROUPBOX = &H7 
Const BS_ICON = &H40 

Const BS_LEFT = &H100 

Const BS_LEFTTEXT = &H20 
Const BS_MULTILINE = &H2000 
Const BS_NOTIFY = &H4000 
Const BS _OWNERDRAW = &HB 
Const BS_PUSHBUTTON = &HO 
Const BS_PUSHLIKE = &H1000 
Const BS RADIOBUTTON = &H4 
Const BS_RIGHT = &H200 
Const BS_RIGHTBUTTON = &H20 
Const BS_TEXT = &H0O 

Const BS_TOP = &H400 

Const BS_USERBUTTON = &H8 
Const BS_VCENTER = &HC0O0 
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Combo Box Control Window Class 


The combo box control's window class describes an ordinary combo box control. 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "COMBOBOX". 


Styles 


CBS_AUTOHSCROLL 
Automatically scroll text to the right when the user types a character at the end of the line. 
CBS_DISABLENOSCROLL 
Show a disable the vertical scroll bar in the drop-down list box if it does not contain enough items 
to scroll. If this flag is not specified, such a scroll bar is not displayed. 
CBS_DROPDOWN 
Display the list box whenever the user clicks the drop-down button. 
CBS_DROPDOWNLIST 
Display the list box whenever the user click the drop-down button, and do not allow the user to 
change the combo box's selection if the list is not dropped down. 
CBS_HASSTRINGS 
The combo box is drawn manually by the application and contains strings. Either 
CBS_OWNERDRAWFICED or CBS_OWNERDRAWVARIABLE must also be specified. 
CBS_LOWERCASE 
Convert all text in the combo box to lowercase letters. 
CBS_NOINTEGRALHEIGHT 
Force the combo box to be exactly the size specified by the application, instead of allowing the 
operating system to slightly resize it to prevent displaying partial selections. 
CBS_OEMCONVERT 
Ensure that text in the combo box can readily be converted into the OEM character set. 
CBS_OWNERDRAWFIXED 
The owner of the combo box is fully responsible for drawing it manually, and all of the items in 
the combo box have the same height. 
CBS_OWNERDRAWVARIABLE 
The owner of the combo box is full responsible for drawing it manually, and the heights of the 
items in the combo box have can be different. 
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CBS_SIMPLE 

Display the list box portion of the combo box at all times. 
CBS_SORT 

Automatically sort the strings added to the combo box. 
CBS_UPPERCASE 

Convert all text in the combo box to uppercase letters. 


Constant Definitions 


Const CBS_AUTOHSCROLL = &H40 

Const CBS_DISABLENOSCROLL = &H800 
Const CBS DROPDOWN = &H2 

Const CBS _DROPDOWNLIST = &H3 

Const CBS_HASSTRINGS = &H200 

Const CBS_LOWERCASE = &H4000 

Const CBS_NOINTEGRALHEIGHT = &H400 
Const CBS_OEMCONVERT = &H80 

Const CBS_OWNERDRAWFIXED = &H10 
Const CBS_OWNERDRAWVARIABLE = &H20 
Const CBS_SIMPLE. = &H1 

Const CBS_SORT = &H100 

Const CBS_UPPERCASE = &H2000 
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Edit Control Window Class 


The edit control's window class descibes a regular text edit box. 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "EDIT". 


Styles 


ES_AUTOHSCROLL 
Automatically scroll the text to the right when the user types a character at the end of the line. 
When the user pressed ENTER, scroll the text all the way back to the left. 
ES_AUTOVSCROLL 
Automatically scroll the text back up when the user presses ENTER on the last line. 
ES_CENTER 
Center the text horizontally. 
ES_LEFT 
Left-align the text. 
ES_LOWERCASE 
Convert all the characters to lowercase as they are typed. 
ES_MULTILINE 
The edit control displays multiple lines of text. If this flag is not specified, it can only display a 
single line of text. 
ES_NOHIDESEL 
Do not hide the selected text in the edit control even if the control loses focus. 
ES_NUMBER 
Only allow digits to be entered into the edit control. 
ES_OEMCONVERT 
Ensure that text in the edit control can readily be converted into the OEM character set. 
ES_PASSWORD 
Display an asterisk for each character typed into the edit control. This cannot be used with 
ES_MULTILINE. 
ES_READONLY 
Do not allow the user to edit the text in the control. 
ES_RIGHT 
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Right-align the text. 
ES_UPPERCASE 
Convert all the characters to uppercase as they are typed. 
ES_WANTRETURN 
Insert a carriage return into a multi-line edit control when the user pressed ENTER, instead of 
implementing the default behavior of ENTER. 


Constant Definitions 


Const ES_AUTOHSCROLL &H80 
Const ES_AUTOVSCROLL = &H40 
Const ES CENTER = &H1 

Const ES_LEFT = &H0O 

Const ES_LOWERCASE &H10 
Const ES _MULTILINE &H4 
Const ES_NOHIDESEL = &H100 
Const ES_NUMBER = &H2000 
Const ES_OEMCONVERT = &H400 
Const ES_PASSWORD = &H20 
Const ES READONLY = &H800 
Const ES_RIGHT = &H2 

Const ES_UPPERCASE = &H8 
Const ES_WANTRETURN = &H1000 
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IP Address Control's Window Class 


The IP Address control's window class describes an IP Address control. This control is similar to an 
edit control, but it is specialized for entering IP addresses in "dotted quad" (a.b.c.d) format. The control 
performs bounds checking on all inputs, preventing the user from entering something that is not an IP 
address. 


Before creating windows from this class, your program must first register it by calling 
InitCommonControlsEx with the appropriate parameters. The name of the class is "SysI[PAddress32". 


Styles 


None. 


Back to the Window Class list. 
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List Box Control Window Class 


The list box control's window class describes an ordinary list box. 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "LISTBOX". 


Styles 


LBS_DISABLENOSCROLL 
Show a disable the vertical scroll bar in the list box if it does not contain enough items to scroll. If 
this flag is not specified, such a scroll bar is not displayed. 
LBS_EXTENDEDSEL 
Allow the user to select multiple items. 
LBS_HASSTRINGS 
The list box is drawn manually by the application and contains strings. Either 
LBS_OWNERDRAWEICED or LBS_OWNERDRAWVARIABLE must also be specified. 
LBS_MULTICOLUMN 
The list box contains multiple columns which are scrolled horizontally. 
LBS_MULTIPLESEL 
Toggle the selection of a string every time the user clicks or double-clicks it. 
LBS_NODATA 
Intended for list boxes having more than 1000 items, do not have the operating system handle any 
of the entries. LBS_OWNERDRAWFIXED must also be specified, and neither LBS_SORT nor 
LBS_HASSTRINGS can be specified. 
LBS_NOINTEGRALHEIGHT 
Force the list box to be exactly the size specified by the application, instead of allowing the 
operating system to slightly resize it to prevent displaying partial selections. 
LBS_NOREDRAW 
Do not redraw the list box when changes are made. 
LBS_NOSEL 
Do not allow the user to select items in the list box. 
LBS_NOTIFY 
Notify the parent window whenever the user clicks or double-clicks a string in the list box. 
LBS_OWNERDRAWFIXED 


http://216.26.168.92/vbapi/ref/other/classes/listoox.html (1 of 3) [9/1/2002 6:21:28 PM] 


Windows API Guide: List Box Control Window Class 


The owner of the list box is fully responsible for drawing it manually, and all of the items in the 
list box have the same height. 
LBS_OWNERDRAWVARIABLE 
The owner of the list box is full responsible for drawing it manually, and the heights of the items 
in the list box have can be different. 
LBS_SORT 
Automatically sort the strings in the list box alphabetically. 
LBS_STANDARD 
Automatically sort the strings in the list box alphabetically, notify the parent window whenever 
the user clicks or double-clicks a string, and display a border around the list box. 
LBS_USETABSTOPS 
Allow the list box to expand tab characters when drawing its strings. 
LBS_WANTKEYBOARDINPUT 
Notify the owner of the list box whenever the user types a key while the list box has the focus. 


Constant Definitions 


Const LBS_DISABLENOSCROLL = &H1000 





Const LBS_EXTENDEDSEL = &H800 
Const LBS_HASSTRINGS = &H40 
Const LBS_MULTICOLUMN = &H200 
Const LBS_MULTIPLESEL = &H8 


Const LBS NODATA = &H2000 


Const LBS_NOINTEGRALHEIGHT = &H100 


Const LBS_NOREDRAW = &H4 


Const LBS NOSEL = &H4000 


Const LBS_NOTIFY = &H1 

Const LBS _OWNERDRAWFIXED = &H10 
Const LBS _OWNERDRAWVARIABLE = &H20 
Const LBS SORT = &H2 

Const LBS_STANDARD = &HA00006 
Const LBS _USETABSTOPS = &H80 


Const LBS_WANTKEYBOARDINPUT = &H400 











Back to the Window Class list. 
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Scroll Bar Control Window Class 


The scroll bar control's window class describes a standalone scroll bar (i.e., one that is not part of 
another control such as an edit control). 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "SCROLLBAR". 


Styles 


SBS_BOTTOMALIGM 
Align the bottom edge of the scroll bar with the bottom edge of its rectangle, using its default 
height. SBS_-HORZ must also be specified. 
SBS_HORZ 
The scroll bar is a horizontal scroll bar. 
SBS_LEFTALIGN 
Align the left edge of the scroll bar with the left edge of its rectangle, using its default width. 
SBS_VERT must also be specified. 
SBS_RIGHTALIGN 
Align the right edge of the scroll bar with the right edge of its rectangle, using its default width. 
SBS_VERT must also be specified. 
SBS_SIZEBOX 
The scroll bar is a size box. 
SBS_SIZEBOXBOTTOMRIGHTALIGN 
Align the lower-right corner of the size box with the lower-right corner of its rectangle, using its 
default width and height. SBS_SIZEBOX must also be specified. 
SBS_SIZEBOXTOPLEFTALIGN 
Align the upper-left corner of the size box with the upper-left corner of its rectangle, using its 
default width and hieght. SBS_SIZEBOX must also be specified. 
SBS_SIZEGRIP 
The scroll bar is a size box with a raised edge. 
SBS_TOPALIGN 
Align the top edge of the scroll bar with the top edge of its rectangle, using its default height. 
SBS_HORZ must also be specified. 
SBS_VERT 
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The scroll bar is a vertical scroll bar. 


Constant Definitions 


Const SBS _BOTTOMALIGN = &H4 

Const SBS _HORZ = &HO 

Const SBS_LEFTALIGN = &H2 

Const SBS_RIGHTALIGN = &H4 

Const SBS_SIZEBOX = &H8 

Const SBS _ SIZEBOXBOTTOMRIGHTALIGN = &H4 
Const SBS _SIZEBOXTOPLEFTALIGN = &H2 
Const SBS_SIZEGRIP = &H10 

Const SBS_TOPALIGN = &H2 

Const SBS VERT = &H1 
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Static Control Window Class 


The static control's window class describes a static control. Static controls are commonly used as labels 
for other controls. 


The button control's window class is registered automatically when Windows starts. The name of the 
class is "STATIC". 


Styles 


SS_BITMAP 
Display the bitmap specified by the static control's text. 
SS_BLACKFRAME 
Draw a frame around the static control in the same color as a window frame. 
SS_BLACKRECT 
Fill the static control with the same color as a window frame. 
SS_CENTER 
Center the text in the static control. 
SS_CENTERIMAGE 
If the bitmap or icon is smaller than the size of the static control, fill the rest of the control with 
whatever color is at the image's upper-left corner. 
SS_ENDELLIPSIS 
Windows NT, 2000: Replace the end of the string with an ellipsis if it is too long to fit in the 
static control. 
SS_ENHMETAFILE 
Display the enhanced metafile identified by the static control's text. Scale the enhanced metafile to 
fit the static control. 
SS_ETCHEDFRAME 
Draw the frame of the static control using the etched edge style. 
SS_ETCHEDHORZ 
Draw only the top and bottom edges of the static control using the etched edge style. 
SS_ETCHEDVERT 
Draw only the left and right edges of the static control using the etched edge style. 
SS_GRAYFRAME 
Draw a frame around the static control in the same color as the screen background. 
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SS_GRAYRECT 
Fill the static control with the same color as the screen background. 
SS_ICON 
Display the icon identified by the static control's text. The static control automatically resizes to 
the size of the icon. 
SS_LEFT 
Left-align the text in the static control. 
SS_LEFTNOWORDWRAP 
Left-align the text in the static control, but do not word wrap. 
SS_NOPREFIX 
Do not use an amperstand character in the string to identify an accelerator prefix, instead 
displaying the amperstands as regular characters. 
SS_OWNERDRAW 
The owner of the static control is fully responsible for drawing the control. 
SS_PATHELLIPSIS 


Windows NT, 2000: Replace characters in the middle of a string holding a path with an ellipsis if 


it is too long to fit in the static control. 
SS_REALSIZEIMAGE 
Clip an image or bitmap if it does not fit inside the static control instead of resizing the control. 
SS_RIGHT 
Right-align the text in the static control. 
SS_RIGHTJUST 
Do not move the lower-right corner of the static control when resizing it to accomodate a bitmap 
or icon. 
SS_SIMPLE 
Draw a simple rectangle and display a single line of left-aligned text in the static control. 
SS_SUNKEN 
Draw a half-sunken border around the static control. 
SS_WHITEFRAME 
Draw a frame around the static control in the same color as the window background. 
SS_WHITERECT 
Fill the static control with the same color as the window background. 
SS_WORDELLIPSIS 
Windows NT, 2000: Truncate text and add ellipses to text which does not fit into the static 
control. 


Constant Definitions 


Const SS_BITMAP = &HE 
Const SS_BLACKFRAME = &H7 
Const SS_BLACKRECT = &H4 
Const.-SS CENTER = &H1 
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Const SS_CENTERIMAGE = &H200 
Const SS_ENDELLIPSIS = &H4000 
Const SS_ENHMETAFILE = &HF 
Const SS_ETCHEDFRAME = &H12 
Const SS_ETCHEDHORZ = &H10 
Const SS_ETCHEDVERT = &H11 
Const SS_GRAYFRAME = &H8 

Const SS_GRAYRECT = &H5 

Const SS_ICON = &H3 

Const SS_LEFT = &H0O 

Const SS_LEFTNOWORDWRAP = &HC 
Const SS_NOPREFIX = &H80 

Const SS_NOTIFY = &H100 

Const SS_OWNERDRAW = &HD 

Const SS_PATHELLIPSIS = &H8000 
Const SS_REALSIZEIMAGE = &H800 
Const SS_RIGHT = &H2 

Const SS_RIGHTJUST = &H400 
Const SS_SIMPLE = &HB 

Const SS_SUNKEN = &H1000 

Const SS _WHITEFRAME = &H9 
Const SS_WHITERECT = &H6 

Const SS_WORDELLIPSIS = &HC000 
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Winsock Error Codes 


The following list identifies the Winsock error codes. These values are used by the WSAGetLastError 
function to report and identify errors caused by other Winsock functions. 


The following Winsock error codes are listed in ascending numerical order. 


WSAEINTR (10004) 
Interrupted Function Call -- A blocking operation was cancelled. 
WSAEACCESS (10013) 
Permission Denied -- An attempt to access a socket was forbidden by its access permissions. 
WSAEFAULT (10014) 
Bad Address -- An invalid pointer address was specified in a function call. 
WSAEINVAL (10022) 
Invalid Argument -- An invalid argument was passed to a function. 
WSAEMEFILE (10024) 
Too Many Open Files -- There are too many open sockets. 
WSAEWOULDBLOCK (10035) 
Resource Temporarily Unavailable -- The specified socket operation cannot be completed 
immediately, but the operation should be retried later. 
WSAEINPROGRESS (10036) 
Operation Now in Progress -- A blocking operation is currently executing. 
WSAEALREADY (10037) 
Operation Already in Progress -- An operation was attempted on a non-binding socket that alredy 
had an operation in progress. 
WSAENOTSOCK (10038) 
Socket Operation on Non-Socket -- An operation was attempted on something that is not a socket. 
WSAEDESTADDRREQ (10039) 
Destination Address Required -- A required address was omitted from a socket operation. 
WSAEMSGSIZE (10040) 
Message Too Long -- A message was sent on a datagram socket that exceeds the internal message 
buffer or some other limit. 
WSAEPROTOTYPE (10041) 
Protocol Wrong Type for Socket -- A protocol was specified that is not supported by the target 
socket. 
WSAENOPROTOOPT (10042) 
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Bad Protocol Option -- An unknown, invalid, or unsupported protocol option or leel was 
specified. 
WSAEPROTONOSUPPORT (10043) 
Protocol Not Supported -- The specified protocol is not supported or is not implemented. 
WSAESOCKTNOSUPPORT (10044) 
Socket Type Not Supported -- The specified socket type is not supported in the address family. 
WSAEOPNOTSUPP (10045) 
Operation Not Supported -- The specified operation is not supported by the referenced object. 
WSAEPFNOSUPPORT (10046) 
Protocol Family Not Supported -- The specified protocol family is not supported or is not 
implemented. 
WSAEAFNOSUPPORT (10047) 
Address Family Not Supported by Protocol Family -- An address incompatible with the requested 
network protocol was used. 
WSAEADDRINUSE (10048) 
Address Already in Use -- An attempt to use the same IP address and port with two different 
sockets simultaneously was made. 
WSAEADDRNOTAVAIL (10049) 
Cannot Assign Requested Address -- The requested address is not valid (given the context of the 
function). 
WSAENETDOWN (10050) 
Network is Down -- A socket operation encountered a network that is down. 
WSAENETUNREACH (10051) 
Network is Unreachable -- A socket operation encountered an unreachable network. 
WSAENETRESET (10052) 
Network Dropped Connection on Reset -- A connection was broken due to "keep-alive" activity 
detecting a failure. 
WSAECONNABORTED (10053) 
Software Caused Connection Abort -- A connection was aborted by software on the host 
computer. 
WSAECONNRESET (10054) 
Connection Reset by Peer -- A connection was forcibly closed by the remote host. 
WSAENOBUFS (10055) 
No Buffer Space Available -- A socket operation could not be performed because the system ran 
out of buffer space or the queue was full. 
WSAEISCONN (10056) 
Socket is Already Connected -- A connect request was made on a socket that is already connected. 
WSAENOTCONN (10057) 
Socket is Not Connected -- An attempt to send or receive data failed because the socket is not 
connected. 
WSAESHUTDOWN (10058) 
Cannot Send After Socket Shutdown -- An attempt to send or receive data failed because the 
socket has already been shut down. 
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WSAETIMEDOUT (10060) 
Connection Timed Out -- The remote host failed to respond within the timeout period. 
WSAECONNREFUSED (10061) 
Connection Refused -- The target machine actively refused the attempt to connect to it. 
WSAEHOSTDOWN (10064) 
Host is Down -- The destination host is down. 
WSAEHOSTUNREACH (10065) 
No Route to Host -- The destination host is unreachable. 
WSAEPROCLIM (10067) 
Too Many Processes -- The Winsock implementation has exceeded the number of applications 
that can use it simultaneously. 
WSASYSNOTREADY (10091) 
Network Subsystem is Unavailable -- The underlying system to provide network services is 
unavailable. 
WSAVERNOTSUPPORTED (10092) 
winsock.dll Version Out of Range -- The Winsock implementation does not support the requested 
Winsock version. 
WSANOTINITIALIZED (10093) 
Successful WSAStartup Not Yet Performed -- The calling application has not successfully called 
WSAStartup to initiate a Winsock session. 
WSAEDISCON (10094) 
Graceful Shutdown in Progress -- The remote party has initiated a graceful shutdown sequence. 
WSATYPE_NOT_FOUND (10109) 
Class Type Not Found -- The specified class was not found. 
WSAHOST_NOT_FOUND (11001) 
Host Not Found -- No network host matching the hostname or address was found. 
WSATRY_AGAIN (11002) 
Non-Authoritative Host Not Found -- A temporary error while resolving a hostname occured, and 
should be retried later. 
WSANO_RECOVERY (11003) 
This is a Non-Recoverable Error -- Some sort of non-recoverable error occured during a database 
lookup. 
WSANO_DATA (11004) 
Valid Name, No Data Record of Requested Type -- The requested name is valid and was found, 
but does not have the associated data requested. 


Constant Definitions 


Const WSAEINTR = 10004 
Const WSAEACCESS = 10013 
Const WSAEFAULT = 10014 
Const WSAEINVAL 10022 
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WSAEMF ILE 1002 
WSAEWOULDBLOCK = 
WSAEINPROGRESS = 


4 
10035 
10036 


WSAEALREADY 
WSAENOTSOCK 
WSAEDESTADDR 
WSAEMSGSIZE 

WSAEPROTOTYP 
WSAENOPROTOO 
WSAEPROTONOS 
WSAESOCKTNOS 
WSAEOPNOTSUP 
WSAEPFNOSUPP 
WSAEAFNOSUPP 
WSAEADDRINUS 
WSAEADDRNOTA 
WSAENETDOWN 

WSAENETUNREA 
WSAENETRESET 
WSAECONNABOR 
WSAECONNRESE 
WSAENOBUFS = 
WSAEISCONN = 
WSAENOTCONN 

WSAESHUTDOWN 
WSAETIMEDOUT 
WSAECONNREF'U 
WSAEHOSTDOWN 
WSAEHOSTUNRE 
WSAEPROCLIM 

WSASYSNOTREA 
WSAVERNOTSUP 
WSANOTINITIA 
WSAEDISCON 




















WOATYPE NOT. 
WSAHOST_NOT_ 


WSATRY_AGAIN 
WSANO_RECOVE 
WSANO_DATA 


10037 
10038 
REQ = 10039 
10040 
E 10041 
PT 10042 
UPPORT 10043 
UPPORT 10044 
P 10045 
ORT 10046 
ORT 10047 
E 10048 
VAIL 10049 
10050 
10051 
10052 
10053 
10054 
10055 
10056 
10057 

10058 

10060 
10061 

= 10064 
ACH 10065 
= 10067 
DY 10091 
PORTED 10092 
LIZED 10093 
10094 
FOUND 
FOUND 
= 11002 
RY 11003 
11004 


CH 


TED 
T 


SED 


10109 
11001 
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Windows API Guide: Articles 


The following is a list of various articles about the Windows API. Each article covers a single subject 
and continues over multiple pages. These articles are frequently written to provide a sort of overview for 
a set of API functions without going into the messy details of each individual function. (Of course, the 
specifics are only a click away in the reference section.) Choose a link below to go to that article's table 
of contents. Articles marked with NEW have been added to the list since the last update of the site. 


e Faking 64-bit Integers 
e Beginner's Guide to the Windows API 


For more articles about the API, visit the API section of the VB-World.net web site. 
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Faking 64-bit Integers 


Introduction 


Usually, the intrinsic Visual Basic data types are sufficient to read information from and send information to API 
functions. The two most important and frequently used data types are String and Long, which is a 32-bit integer data 
type. Since Windows is a 32-bit operating system, it almost exclusively uses 32-bit integers throughout its API. 


However, 32 bits of integer data are not always enough. For some functions, a 64-bit integer data type is necessary to 
encompass the entire range of possible information. The ULARGE_INTEGER structure used by the API stores such a 
64-bit integer by separating it into high-order and low-order halves of 32 bits each. This format is, sadly, not convenient 
for actually reading the data in the structure. To easily read and write to these structures, a 64-bit integer data type is 
necessary. And alas, Visual Basic has no true 64-bit integer data type. 


The Currency Data Type 


Fortunately, all is not lost! Visual Basic has the Currency data type. The Currency data type was initially created by the 
designers of Visual Basic to allow precise computations to be made on monetary values. The Single and Double floating- 
point data types are insufficient because they can only support a limited number of significant digits. Beyond that 
number of digits, some rounding occurs. The Currency data type combines the exactness of integer data types with a few 
fixed decimal places to allow subdivisions of a currency unit (such as a cent). 


Internally, the Currency data type actually is a 64-bit integer. However, Visual Basic scales down by a factor of 10,000 

to produce four digits after the decimal point. So, although the data type is a 64-bit integer, Visual Basic will display the 
value of any Currency-type variable as having a decimal point followed by four digits. Therefore, in order to display a 64- 
bit value copied into the variable correctly, you must first multiply the variable by 10,000. This will shift the decimal 
point four places to the right, resulting in the display of the actual value. 


Example 


Here is an example of how the Currency data type can be used to display a 64-bit integer retrieved from an API function. 
The GetDiskFreeSpaceEx reports all of its data as 64-bit integers. For disk space, 32-bit integers are too small; 





otherwise, the function would be limited to hard drives having a total storage space of less than 4.0 GB. Clearly, this is 
too small for modern disks! 


After retrieving the information from the function, the following code copies it into a Currency-type variable. Then, after 
multiplying it by 10000 to move Visual Basic's decimal point, the free space of drive C: is properly stated. 


Dim userbytes As ULARGE INTEGER ' bytes free to user 
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Dim totalbytes As ULARGE INTEGER ' total bytes on disk 
Dim freebytes As ULARGE INTEGER ' free bytes on disk 


Dim tempval As Currency ' display buffer for 64-bit values 
Dim retval As Long ' return value of f 














unction 





' Get information about the C: drive. 
retval = GetDiskFreeSpaceEx("C:\", userbytes, totalbytes, freebytes) 





' Copy totalbytes into the Currency data type. 
CopyMemory tempval, totalbytes, 8 





' Multiply by 10000 to move Visual Basic's decimal point to the end of the actual 
number. 

tempval = tempval * 10000 

' Display the total number of bytes on C:. 

Debug.Print "Free Space on the C: drive:"; tempval; "bytes" 





Manipulating 64-bit Integers 


Although you may be storing a true 64-bit integer inside a Currency data type, Visual Basic believes there is a decimal 
point inside the value whether you want one there or not. Therefore, you must take care when performing some 
arithmetic operations on true 64-bit values. This involves moving the decimal point to preserve the actual integer, instead 
of the value Visual Basic believes you are storing inside of it. 


Addition and Subtraction 


No conversion factor is necessary to add or subtract 64-bit integers from one another. Simply add or subtract Currency 
types as you would any other data type values. 


Multiplication 


When multiplying two 64-bit integers in Currency form, you must multiply the result by 10,000 to move the decimal 
point to the proper place. However, if you wait to multiply by 10,000 until after you calculate the initial product, it is 
very possible that you will have lost part of the calculation due to internal rounding off. Therefore, to multiply two 64-bit 
integers in Currency form, use the following formula: 


product = 10000 * first * second 
Division 


Like multiplication, division of two 64-bit integers in Currency form requires a correction factor. However, in this case, 
the quotient must be divided by 10,000. To minimize internal rounding off of significant digits, you should divide by 
10,000 only after calculating the initial quotient. To divide two 64-bit integers in Currency form, use the following 
formula: 


quotient = dividend / divisor / 10000 


Limitations 
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Although using the Currency data type to "fake" 64-bit integer support in Visual Basic should work in most cases, there 
remains the problem of data range. Because the value must be multiplied by 10,000 to display properly, values at the 
extremes of the 64-bit integer range will cause an Overflow error if you try to display them. Thus, the Currency form of 
64-bit integers in Visual Basic has a display range from -372,036,854,775,808 to 372,036,854,775,807. So while you 
cannot use the full range of 64-bit values, nevertheless these fake 64-bit integers greatly extend the range offered by the 
intrinsic 32-bit data type. 


Of course, this limitation does not apply to 64-bit integers that do not need to be displayed for the user. The Currency 
data type itself can store the entire 64-bit range from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. Note, 
however, that at these extremes, the methods presented earlier for multiplying and dividing these values may fail. They 
depend on having the "extra room" available in the storage space that may not be present past the trillions. Again, 
however, despite these limitations, using the Currency data type as a pseudo-64-bit integer data type makes it 
significantly easier to use those API functions that, like GetDiskFreeSpaceEx, use 64-bit values in their parameters. 


Back to the Article list. 
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Beginner's Guide to the Windows API 


Abstract: In order to use the Windows API effectively in your programs, you must first learn a number 
of fundamentals about how the API operates. This article illustrates the usage of functions, structures, 
named constants, callback functions, and messages to empower hundreds of API functions. Other API- 
based ideas such as handles and device contexts also receive mention. Finally, important issues about the 
actual implementation of direct API calls in Visual Basic is mentioned. 
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Introduction to the Windows API 
What is an API? 


The acronym API stands for Application Programming Interface. It serves as a software interface to be 
used by other programs. Just as a number keypad is the interface for a calculator, an API is the software 
interface for things such as operating systems. The API of an operating system is the fundamental reason 
why different operating systems are incompatible -- why, for example, a Macintosh-based piece of 
software cannot run on a system running Windows 98 (without an emulator, at least). Because Mac OS 
and Windows have completely different APIs, programs designed to use one cannot use the other. The 
core function of an emulator is "converting" the API calls of one program into the API calls of the 
operating system running it; it acts as a sort of translator between the two APIs. 


An API is truly the fundamental level of higher-level programming. In high-level programming, a 
program often does not execute tasks itself but instead tells some other program to do it. In the case of 
operting systems, programs frequently delegate various tasks to the underlying operating system. For 
example, if a program wishes to write data to a disk, it does not manually send commands to the hard 
disk itself to seek, read, write, etc. bit by bit. Instead, is merely tells the operating system to write a 
certain amount of data to a specified file, and the operating system handles the dirty work. The 
advantages of this arrangement are obvious. Designers of software do not have to worry about the basic, 
fundamental chores involved in every program (such as disk access, memory allocation, drawing on the 
monitor, etc.) by hand, saving both time and final program size. Also, suppose that a more efficient way 
to render an image on a monitor is created. If each individual program directly handled all its graphical 
output, each program would need to be updated to take advantage of this development. Instead, if they all 
use the API, and the operating system is upgraded to include this new method, every program now 
enjoys the benefits of the more efficient system without a single modification. 


What Does the Windows API Do? 


Basically, the Windows API handles everything that makes Windows what it is. Naturally, it 
encompasses aforementioned things such as drawing on the monitor, disk access, printer interface, 
Internet usage, etc. However, it also provides most of the features common to all Windows-based 
software. For example, the common dialog boxes (Open, Save As, Choose Font, etc.), the Windows 
shell, list boxes, operating system settings, and even windows themselves are provided by the Windows 
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API. Windows-based programs make extensive use of the Windows API in almost every task. Even if 
you don't use the API explicitly in your programming, the programming language software will almost 
always put calls to the Windows API in the generated program to handle various tasks. The Windows 
API in all encompasses a surprising vast number of topics. 


Where is the Windows API? 


Almost every function in the Windows API is located in one of the DLL (Dynamic Link Library) files 
found in the C:\Windows\System directory (or wherever the Windows System directory is). These DLL 
files "export" functions inside of them -- they allow external programs to use their functions. This design 
allows any Windows-based program to access any API function relatively easily. The bulk of API 
functions are found in user32.dll (user interface functions), kernel32.dll (operating system kernel 
functions), and gdi32.dll (graphics device interface functions), and shell32.dll (Windows shell functions). 


What are the Components of the Windows API? 


Although so far on this page only the API functions have been refered to, the functions themselves are 
only one part of the entire API. The following list identifies all the objects which make up the Windows 
API. 


e Functions - As already mentioned, the functions make up the core of the Windows API. They are 
the actual code which accomplish the various tasks handled by the API. They are stored in the 
DLL files and can be accessed easily from any Windows-based program. 

e Structures - Structures, combinations of multiple individual variables, are frequently used in the 
Windows API to store groups of related information. Many API functions require that a structure 
be passed to them in order to more conveniently transfer a large amount of information without an 
overly large number of parameters. Although these structures are used by the API functions, your 
program must properly define them itself. 

e Named Constants - The Windows API frequently uses otherwise esoteric numeric codes for 
information. Naming these constants provides a more convenient way to refer to these values in 
code. Sometimes these constants are used as flags: the data value can be a binary OR of multiple 
individual flags, allowing one value to store multiple pieces of information. As with structures, 
the named constants must be explicitly defined in your program. 

e Callback Functions - Conceptually, a callback function is the reverse of an API function. A 
callback function is defined completely in your program. This function is then called by an API 
function routine when it executes its task. Callback functions provide a way to have your program 
play a critical role in a task. Callback functions are used frequently in enumerations, where all the 
members of some group are identified one by one; in this case, a callback function is used to 
allow your program to somehow process each item found belonging to the group. 

e Messages - In a way, messages are a special type of named constant. While they are also numeric 
values given names, they behave differently. Messages are sent to objects (especially windows) to 
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tell them to do something. Sending a message does not in itself do anything; rather, it instructs 
some other object to execute one or more events. 


Why Bother? 


Granted, using the Windows API to do stuff does have drawbacks. First, API functions are significantly 
more error-prone than using intrinsic programming language functions. Because the entire API library 
was created in C++, the information passed to and from the functions must be compliant with C++ 
syntax, regardless of the programming language you are using. This can cause hard-to-find problems 
regarding pointers, terminating nulls, and other things you'd rather not have to deal with. Furthermore, 
API functions are prone to fail spectacularly. Instead of making a nice little error dialog appear, they can 
easily crash the entire program, forcing it to shut down with a GPF (General Production Fault). And 
since Visual Basic comes with almost no API documentation whatsoever, you need to find other 
resources (such as this site!) to learn what functions even exist, let alone how to use them. So why bother 
at all? 


Simple: because API functions are also significantly more powerful than the intrinsic features of pretty 
much any programming language, especially Visual Basic. For example, in VB you can set the title bar 
text of any window you created using its Caption property. But how do you change the text of a window 
not created by your program? The SetWindowText API function comes in handy, not to mention others. 
Another example: if you want to use the Open File common dialog box without the API, you need to 
distribute an OCX library of about 90KB along with your program. Using the GetOpenFileName API 
function, you can avoid the overhead be accessing what the OCX really serves as a front-end for. And if 
you want to, say, read and write the Windows registry or use the joysticks connected to the computer, 
Visual Basic doesn't have the necessary tools. However, even those become possibly using the Windows 
API! 


So, in summary, if Visual Basic or whatever language you use has the ability to perform a certain task, 
you're better off not using the Windows API for that. You'll have easier requirements and the security of 
having a more reliable mechanism. But if you want to add more power to your program which VB can't 
provide, the Windows API is your only way to go. This guide endeavors to provide the Visual Basic user 
with the information and examples necessary to allow him or her to successfully implement hundreds of 
API functions (as necessary) in his or her programs. 


(no previous page) | Contents of Introduction | Forward to Part 2 >> 
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Basics of Using API Functions 


Introduction 


On the surface, using a function from the Windows API in a Visual Basic program seems fairly simple 
and straightforward. (Don't worry -- we'll get to the complicated stuff soon enough!) Before you begin 
using the function, you must first declare it somewhere in your program. Then, you can use the function 
just as you would any other function in Visual Basic. This page explains how to declare a function and 
demonstrates some simple examples of how to use them in code. 


Declaring the Function 


Before an API function can be using in Visual Basic, it must first be declared. By declaring the function, 
you tell Visual Basic where it can find the function. The declaration identifies the name of the function, 
the DLL file it appears in, the parameters it requires, and the data type (if any) it returns. Armed with this 
information, Visual Basic knows where to find the API function whenever it is invoked. (This procedure 
isn't limited to Windows API functions. If you import any functions from a DLL file, they must be 
declared in the same manner. Using other DLL function libraries is not covered by this site.) 


The below statement illustrates the syntax of the declaration. The Declare statement in Visual Basic is 
used to declare a function. The Declare statement can only appear in the (declarations) section of a form 
or module. If it appears in a form, the declaration must be Private, making the function only available 
inside that form. If it appears in a module, the declaration can be either Public or Private. The Public 
keyword makes the function available throughout the entire program, whereas the Private keyword 
restricts its use to within the module itself. 


[{Public | Private}] Declare Function function_name Lib "DLL filename" 
[Alias "function_alias"] (argument_list) As data_type 


Since this syntax might seem intimidating at first, the following list identifies the various components of 
the Declare statement. 


function_name 
The name of the API function. This is the name by which Visual Basic will refer to the function 
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everywhere else in your code. In theory, you can make this any name you want (as long as you 
use the proper Alias clause), but it's safest to make this the "official" name of the function in the 
Windows API. 

DLL_filename 
The name of the DLL file which stores the function. This does not include the path, because the 
Windows System directory (where all API DLL files appear) is assumed. Actually, the filename 
does not even have to specify the .dll extension, so user32 and user32.dIl are synonymous. 
However, watch out for some API functions which do not occur in DLL files; for example, some 
printer-using API functions appear in winspool.drv. In cases like that, the extension must be 
specified. 

function_alias 
(Optional) The name of the function as it appears in the DLL file. This is important because 
almost every function which has a string as a parameter has two versions: the ANSI version (used 
by most speaking languages) and the Unicode wide-character version (used by wide-character set 
languages such as Chinese). Since this web site is designed primarily for English speakers, the 
ANSI version of the functions are always used. When an ANSI/Unicode pair appear in a DLL, 
they are given slightly different names: the ANSI version ends with the letter A, and the Unicode 
version ends with the letter W. For example, the two versions of CompareString are called 
CompareStringA and CompareStringW. 

argument_list 
A list of the zero or more arguments which the function needs. This is very similar to any other 
argument list in Visual Basic, but its added features in the Declare statement will be discussed in 
the next section. 

data_type 
The name of the data type which the function returns. This will almost always be a Long, 
although a few function returns a String. 


In case you were wondering, some functions do not return any value. For those functions, the Declare 
statement takes a slightly different format, presented below. 


[{Public | Private}] Declare Sub function_name Lib "DLL_filename" 
[Alias "function_alias"] (argument_list) 


The Argument List 


The argument list specifies how many and what kinds of variables are passed to the function. Its format 
is very similar to the argument list of a program-defined Function or Sub. The following line illustrates 
the syntax of the argument list. Keep in mind that some functions take an empty argument list -- they are 
not passed any data whatsoever. 


[{ByVal | ByRef}] argument_name As data_type, 
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Except for the option for By Val and ByRef, which will be introduced shortly, the format of the argument 
list is similar to what you are probably used to already. But for review, here's what the different symbols 
in the argument list syntax represent. 


argument_name 
The name given to the argument. When declaring API calls, this really only serves to give a clue 
as to what the parameter represents. Although you should use the argument name suggested by 
this guide (or by other API documentation), you are actually free to choose whatever name you 
wish. 

data_type 
The data type of the individual argument. This could also be the "Any" keyword, which allows 
information in any data type to be passed. 


Data Types 


As you already know, a data type specifies the size and format of a variable or argument to a function. 
API functions support only a limited number of data types compared to those available in Visual Basic. 
The following list identifies which data types can be used in API function declarations. 


Byte 
An 8-bit integer. 
Integer 
A 16-bit integer. 
Long 
A 32-bit integer. 
String 
A variable-length string. 


In addition to the aforementioned data types, any of the API structures can also be used. Structures will 
be dealt with in a later page in this introduction. Out of the four data types mentioned above, Long and 
String are the most common. Since Windows is a 32-bit operating system (starting with Windows 95 and 
Windows NT 3.1), almost all numbers used in its API are Longs, 32-bit integers. Strings are also used 
frequently because they are pretty much the only way to store strings. 


ByVal and ByRef: An Introduction 


The ByVal and ByRef keywords specify the method used to pass a parameter to the API function. These 
two methods are extremely different and nonsubstitutable -- you can never use ByRef in place of ByVal 
and vice versa. When declaring API functions, the ByRef method is assumed to be used unless the ByVal 
keyword is used explicitly. Therefore, in API function declares, you will usually never see ByRef 
explicitly used; it will only be apparent by the lack of the ByVal keyword. 
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The actual meanings of ByVal and ByRef are beyond the scope of this individual page, although 
knowledge of their actual interpretations is crucial for using the more sophisticated API functions. At this 
point, however, the gist of these two keywords can be summarized as follows. 


ByVal literally means "By Value." The value of whatever variable or expression is passed as the 
parameter. This method prevents the function from altering the contents of a variable passed ByVal. For 
example, if you have a variable MyVar that you pass ByVal to an API function, the API function cannot 
possibly edit the contents of MyVar. 


ByRef literally means "By Reference." Instead of passing the contents of the variable, this method passes 
a sort of reference to the variable itself. This allows the function to edit the contents of the variable 
passed as that parameter. Note that expressions or constants cannot be passed ByRef -- only variables. 
For example, a variable MyVar passed ByRef to an API function may very well be edited by that 
function. In fact, ByRef parameters are usually used to allow the function to "return" information outside 
its single return value. 


There are a few additional points to remember about ByVal and ByRef: 


1. Strings are always passed ByVal. However, the API function is able to edit the contents of the 
string variable, as if it had been passed ByRef. The reasons for this are beyond the scope of this 
page. 

2. User-defined structures, including structures used by the API, are always passed ByRef. 

3. Arrays are always passed ByRef when the entire array is meant to be passed to a function. When 
passing an entire array to a function, VB syntax mandates that you "pass" the first element of the 
array to the function. However, in reality you are passing the entire array if that parameter is 
defined to by ByRef. If the parameter is instead ByVal, passing the first element of the array does 
just that. 

4. Numeric variables can be passed either ByVal or ByRef, depending on the requirements of the 
function. 


Examples 


This page has presented a lot of information about the Declare statement in Visual Basic. At first, using 
Declare may seem very difficult, especially since I am saving some of the uglier details for a later page 
of this API introduction series. Fortunately, you probably will never write a Declare yourself. You can 
get the Declares for API functions from the API Text Viewer that comes with Visual Basic, or you can 
get the Declares off the pages of this site. With these resources, declaring API functions becomes just a 
copy-and-paste operation. Nevertheless, a number of examples of the Declare statement will help you 
understand the contents of this page. 
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The following list presents a number of examples of the Declare statement as well as a brief explanation 
of what they mean. Don't worry about what these functions actually do at this point, although you can 
read about any of them elsewhere in this site. What's important here is understanding the mechanics of 
the Declare statement. 


e The following line declares a function which does not take any parameters and returns a 32-bit 
integer: 
Declare Function GetDesktopWindow Lib "user32.d11" () As Long 

e The following line declares a function which takes a single 32-bit parameter by value and does 
not have a return value: 
Declare Function Sleep Lib "kernel32.dl1ll1" (ByVal dwMilliseconds 





As Long) 

e The following line declares a function which takes two 32-bit parameters by value and returns 
another 32-bit integer: 
Declare Function ReleaseDC Lib "user32.d11" (ByVal hWnd As Long, 
ByVal hDC As Long) As Long 

e The following line declares a function which takes one string as a parameter and returns another 
string. Notice how this function, like almost all string-using API functions, requires an alias: 
Declare Function CharUpper Lib "user32.dl11" Alias "CharUpperA" 








(ByVal lpsz As String) As String 

e The following line declares a function which takes one RECT structure as a parameter and returns 
a 32-bit integer: 
Declare Function CreateRectRgnIndirect Lib "gdi32.d11" (lpRect As 
RECT) As Long 

e The following line declares a function which takes three parameters. The first two parameters are 
32-bit integers passed by value. The third parameter is a 32-bit integer passed by reference -- that 
variable's value is set by the function. The function also returns a 32-bit integer: 
Declare Function SHGetSpecialFolderLocation Lib "shell32.dl11" 
(ByVal hwndOwner As Long, ByVal nFolder As Long, ppidl As Long) 
As Long 

e Finally, this declaration encompasses a number of different ideas simultaneously: 
Declare Function RegCreateKeyEx Lib "advapi32.dl1" Alias 
"RegCreateKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, 
ByVal Reserved As Long, ByVal lpClass As String, ByVal dwOptions 
As Long, ByVal samDesired As Long, lpSecurityAttributes As 
SECURITY ATTRIBUTES, phkResult As Long, lpdwDisposition As Long) 
As Long 




















That completes this section of the Introduction to the Windows API. If that last example declaration 
confuses you, you should review the contents of this page to cover any ideas which are still fuzzy. 
Remember, the rest of this series of pages builds on the fundamentals outlined above. 
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Concepts in the Windows API 
Introduction 


Although this series has already discussed the mechanics of declaring and using API functions, it has not yet dealt with 
some basic concepts used throughout the Windows API. Few of these ideas appear explicitly in Visual Basic, although 
their knowledge and mastery is crucial for using the API effectively. This page identifies these important ideas, explains 
them, and briefly demonstrates where they can appear. 


Handles 


Handles are internal constructs of the Windows API. The API uses handles to keep track of a large number of objects 
throughout the system. For example, open files, windows, open registry keys, brushes, icons, menus, and many other 
objects are refered to using handles. In fact, their handles are really the only way a program is able to manipulate these 
objects, since Windows itself handles all the little details. 


In reality, a handle refers to an internal structure in Windows detailing various information and properties of the object. 
However, there is no way to access this structure directly; that's why it is internal! The handle itself is just a 32-bit integer 
used by a program calling API functions. In Visual Basic, the Long data type is used to store handles. As far as Visual 
Basic is concerned, there is no special difference between a handle and any other 32-bit integer value. The significance of 
a handle only becomes apparent when it is passed as a parameter to an API function. 


As already mentioned, most objects under Windows have handles attached to them. This includes form windows, 
command buttons, picture boxes, and many other objects which Visual Basic can create and manage for you. Fortunately, 
these objects, when created using Visual Basic, have a property called .hWnd. This property equals the handle to that 
window. So, for example, if you have a command button called Command1, you can use the property Command!.hWnd 
to get the handle to the command button (remember that buttons, forms, etc. are all just types of windows). This handle 
can be given to any API function which can use it properly. 


The following example demonstrates how handles can be used. The example uses the API to draw the first icon stored in 
the file C:\Windows\sol.exe. This example uses three handles. The first handle, App.hInstance, is merely a handle to this 
particular instance of the example program. The second handle, called hIcon, is a handle to the icon used to depict the 
icon. The third handle, Form1.hDC, is a handle to Form1's device context. Device contexts are explained in the next 
section. 








Dim windir As String ' receives path of Windows directory 

Dim slength As Long ' receives length of Windows directory path 
Dim exename As String ' full filename of sol.exe 

Dim hIcon As Long ' handle to the display icon 

Dim retval As Long ' generic API function return value 
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' First, since the Windows directory might not be C:\Windows, 
' obtain the actual path of it. 

windir = Space (256) ' make enough room in the buffer 

' Place the directory name in the buffer. 

slength = GetWindowsDirectory(windir, 256) 











' Remove the blank space from the buffer. 
windir = Left (windir, slength) 





' Combine the Windows directory path and the filename. 








exename = windir 
If Right (exename, 1) <> "\" Then exename = exename & "\" 
xename = exename & "sol.exe" 





' Now, extract the first icon stored in the Solitaire program. 
hIcon = ExtractIcon(App.hInstance, exename, 0) 














' Draw this icon in the upper-left corner of Forml. 
retval = Drawlcon(Forml.hDC, 0, 0, hIcon) 

















' Destroy the loaded icon to free resources. 
retval = DestroylIcon (hIcon) 

















Device Contexts 


Device contexts have a similar initial appearance to handles. Like a handle, a device context is actually an internal data 
structure inside Windows which cannot be accessed by your program. As the name suggests, a device context is an 
intermediary between your program and a physical device, such as a display monitor, the keyboard, or the printer. Device 
contexts are important because they allow your program to treat different models and brands of one type of device (say, 
printers) in identical ways. By using device contexts, your program doesn't care if the user has an HP DeskJet or a Canon 
BubbleJet because the device contexts for both are almost identical. 


As already mentioned, a program cannot access the device context of a device directly. Instead, it can only use a handle to 
the device context. It is important to remember that the device context and a handle to a device context are not the same 
thing! A device context is not accessable directly by a program. A handle to a device context is, like any other handle, a 32- 
bit integer. 


Interestingly, windows themselves are considered to be devices in the sense that they can have a device context. This 
allows graphics API functions to draw on and otherwise manipulate the appearance of a window. Fortunately again, 
Visual Basic automatically assigns the .hDC property of such windows to the handle to that window's device context. This 
allows calls to API functions to reference VB-created objects relatively easily. 


The following example demonstrates how a device context can be used. Here, a rounded rectangle is drawn on the form 
window Form1. The rounded rectangle is drawn with a thin white pen and is filled with a green diagonally cross-hatched 
brush. Notice that whenever an API function needs to do something to Form1, it requires the handle to its device context 
(Form1.hDC). You can also see those all-important handles used to identify the brush and pen, not to mention the device 
context! 


Dim hPen As Long ' handle to the pen 

Dim hBrush As Long ' handle to the brush 

Dim hOldPen As Long ' handle to Forml's previous pen 

DIm hOldBrush As Long ' handle to Forml's previous brush 
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Dim retval As Lon : eneric API return value 
g g 


' (Recall that all constant definitions appear on the pages which 
' explain the function they are used by. So here, the constant 
' WHITE_PEN is defined on GetStockObject's page.) 














' Get a handle to the desired pen. 

hPen = GetStockObject (WHITE_PEN) 

' Get a handle to the desired brush. 

hBrush = CreateHatchBrush(HS_DIAGCROSS, RGB(0, 255, 0)) 



































' Select the new pen and brush for use by Forml. 
hOldPen = SelectObject (Forml.hDC, hPen) 
hOldBrush = SelectObject (Forml.hDC, hBrush) 

















' Draw the rounded rectange on Forml. 
retval = RoundRect (Forml.hDC, 100, 100, 300, 200, 5, 5) 














' Select the previous pen and brush for Forml and delete 















































' the ones created by this example. 

retval = SelectObject (Forml.hDC, hOldPen) 
retval = SelectObject (Forml.hDC, hOldBrush) 
retval = DeleteObject (hPen) 

retval = DeleteObject (hBrush) 

Pointers 


A pointer is simply a 32-bit integer variable which holds a memory address. This memory address is usually the location 
of some other object, such as a structure, another variable, or a structure. Despite this deceptively simple definition, 
pointers are a core component of computer programming, especially in the C++ language. Interestingly, Visual Basic has 
no intrinsic support for pointers whatsoever (well, that's not quite true, but the exception will come in a later page of this 
series), although you can use the Long data type to store a pointer. Presumably, VB has no explicit pointers to make 
programming easier. (A later page in this series will illustrate some places where Visual Basic hides the pointers it uses.) 


Because the DLLs which constitute the Windows API were built using some flavor of C++, many of them desire pointers 
to one object or another as one or more of their parameters. At this time, it is sufficient to say that 99.5% of the time 
Visual Basic successfully relieves the burden of creating all the otherwise necessary pointers to structures and strings and 
other variables. However, the other .5% of the time, your code will need to generate its own pointers, usually by using 
other API functions. 


The following example demonstrates one instance where your program ought to manipulate a pointer explicitly. Here, a 
PIDL -- a pointer to an ITEMIDLIST structure -- is used to help display the icon used for the Favorites folder in the 
Windows system shell. Because the API is kind enough to create and delete [TEMIDLIST structures itself, there is no 
need to access the structure directly; in fact, doing so will almost always generate some error. Therefore, the example 
blissfully uses a pointer to such a structure. (Once again, handles and device contexts pop up in this example. See how 
fundamental they are?) 


If you have problems understanding this example, you might want to skip ahead to the page of this series about structures, 
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since this example uses one structure. I couldn't think of any good examples of pointers that didn't necessitate using one 
structure or another. 


























Dim pidl As Long ' PIDL to the Favorites folder 
Dim fileinfo As SHFILEINFO ' stores file information 
Dim retval As Long ' generic return value 
































' Get a PIDL (pointer to an ITEMIDLIST) which refers to the 


' Favorites folder in the Windows shell. (pidl is the PIDL) 
retval = SHGetSpecialFolderLocation(Forml.hWnd, CSIDL_FAVORITES, pidl) 



































' Now get a little info about the Favorites folder. Specifically, the following 
' function call merely requests the folder's icon. 
retval = SHGetFileInfo(pidl, 0, fileinfo, Len(fileinfo), SHGFI_ICON Or SHGFI_PIDL) 


















































' The handle fileinfo.hIcon now refers to the Favorites folder's 
' icon in the shell. Display it on Forml. 
retval = DrawIcon(Forml.hDC, 0, 0, fileinfo.hIcon) 




















' Destroy the icon to free resources. 
retval = DestroyIcon(fileinfo.hIcon) 




















Footnote: Combining Flags 


In the call to SHGetFileInfo in the above example, you see your first exposure to flags. A flag is simply a type of named 
constant. The special thing about flags is that they can be combined with other related flags. This allows multiple on/off or 
yes/no options to be passed to a function using a single parameter. Above, you see that the function is told to retrieve a 
handle to the icon (SHGFI_ICON) and that the first parameter is a PIDL to the folder (SHGFI_PIDL). 


When combining multiple flags, the bitwise Or operator should always be used. This assures an error-free combination of 
the flags (as long as the attempted combination is valid). Why not use the addition operator (+) to combine the flags. 
Although the effect may be the same, using regular addition can have some unexpected consequences. To demonstrate the 
problem which can appear when using addition, I will create my own hypothetical function. 


Consider a message-box-like function which accepts a single parameter. This parameter is a combination of the following 
flags specifying the buttons you want to appear in the box: 





Const PK_OK = 1 ' OK button only 

Const PK_CANCEL = 2 " Cancel button only 
Const PK_OKCANCEL = 3 ' OK and Cancel buttons 
Const PK_HELP = 4 ' Help button only 


Remember that this is a hypothetical example -- these flags do not exist in the API. You will notice that the 
PK_OKCANCEL flag is actually the bitwise Or combination of the PK_OK and PK_CANCEL flags (1 Or 2 = 3) and not 
a separate flag in itself. This is done to simplify things for the programmer, since the OK and Cancel buttons frequently 
appear together. 


Now suppose that a novice API programmer decides he wants to use the OK and Cancel buttons. At first, he sends merely 
the PK_OK flag to the function: 
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retval = ExampleFunction (PK_OK) 


Accordingly, only the OK button appears in the dialog box. Realizing his mistake, he decides to fix his code by adding the 
PK_OKCANCEL flag as one of the flags. So he enters the following: 


retval = ExampleFunction(PK_OK + PK_OKCANCEL) 


And he expects both the OK and Cancel buttons to appear. But instead the Help button appears by itself! Why? Notice that 
PK_OK + PK_OKCANCEL = PK_HELP (i.e., 1 + 3 = 4). His expression actually evaluated to the value for the 
PK_HELP flag by itself! Had he used the bitwise Or operator has follows, he would have entered: 


retval = ExampleFunction(PK_OK Or PK_OKCANCEL) 


That line executes as expected, displaying the OK and Cancel buttons. Why? Notice that PK_OK Or PK_OKCANCEL = 
PK_OKCANCEL (i.e., 1 Or 3 = 3). Using Or instead of addition guarantees that accidentally specifying the same flag 
twice will not cause an error. Of course, it is sloppy coding, so you should avoid doing so anyway. Of course, in the "real" 
world this error might not be so obvious. (For example, see the SetWindowPos function; the SWP_DRAWFRAME and 
SWP_FRAMECHANGED flags are actually identical, and adding the two together gives you the SWP_SHOWWINDOW 
flag instead.) 
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Using API Structures 


Introduction 


This page begins the discussion of another key component of the Windows API: the structure. Structures 
allow a function to receive or return a large amount of information without cluttering the argument list. 
Structures almost always group related information, allowing related data to remain in a single package. The 
usage of structures is important in the more complex (and therefore more useful) API functions. 


Structure Fundamentals 


A structure is an object used in programming to group multiple related variables. A structure consists solely of 
one or more individual variables having any data type (including that of another structure). To use a structure, 
create a variable having that structure as its data type. This structure variable now has one of each member of 
the structure inside of it. Usually these data members store information about a related thing. 


Structures in Visual Basic 


To define a structure in Visual Basic, the Type block is used. Structure definitions can only appear in the 
(declarations) section of a form or module. The Type block has the following syntax: 


[ (Public | Private}] Type type_name 
memberl As data_typel 
member2 As data_type2 


End Type 


The Public/Private indicator works the same way as it does for functions. Structures are public unless 
otherwise specified. The following list identifies the various components of the Type block: 


type_name 
The name to give the structure. This name will then be used as the data type of whatever variables you 
want to use the structure. 

memberl, member2, ... 
The name of an individual member of the structure. These are effectively variables stored in the 


http://216.26.168.92/vbapi/articles/intro/part04.html (1 of 4) [9/1/2002 6:23:51 PM] 


Windows API Guide: Using API Structures 


structure. 

data_typel, data_type2, ... 
The data type of a particular item in the structure. Valid types include the Byte, Integer, Long, and 
String data types. This could also be another structure (although of course not the one being defined). 
This could also be a fixed-length string, having the data type of String * numchars, where 
numchars is the size in characters of the fixed-length string. 


For example, consider the following hypothetical structure: 





Type EXAMPLESTRUCT 
longvar As Long 
another As Long 
s As String 

fixed As String * 24 
astruct As RECT 

End Type 





In this example, the structure has five data members. 1ongvar and another are both 32-bit integers. s is a 
regular string, but fixed is a string which has a fixed length of 24 characters. ast ruct is a variable of the 
RECT structure type. 





To access a data member of the structure (after you have defined a variable to use the structure), simply use 
the . (period) operator between the variable name and the member name. Apart from that, the data members 
inside the variable can be treated exactly as a regular variable. For example, all of the following code is 
perfectly valid: 





Dim ex AS EXAMPLESTRUCT ' ex is the structure 

ex.longvar = 54 

ex.another = ex.longvar * 65 - 9 

ex.s = "This is a sample string." 

ex.fixed = "Fixed-length string." ' this will be right-padded with spaces 





Debug.Print ex.fixed 
ex.astruct.left = 54 


API Structures 


Many functions in the Windows API use structures as one or more of their arguments. This allows large 
amounts of related information to be passed to and from the function relatively easily. Although some 
structures are used by dozens of different functions, you cannot link to a structure in any of the API DLL files. 
Instead, you must define any API structures you use yourself in your program. Naturally, you must use the 
exact same definition of the structure in your code, or else fatal errors are likely to appear. For example, if you 
wish to use the RECT structure in your program, the following definition must also appear in your program: 
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Type RECT 
left As Long 
top As Long 
right As Long 
bottom As Long 
End Type 


Here, the RECT structure provides a convenient way to keep the necessary coordinates of a rectangle grouped 


together. Each member of this particular structure holds one component of one of the two coordinate pairs 
used to identify the rectangle. Without this structure, four individual variables would be necessary to hold the 
same information. This structure is commonly used in graphics API routines. 


Still not convinced about the usefulness of structures? This example taken from the API should be able to 
persuade you. There are two functions that create a font object: CreateFont and CreateFontIndirect. Both take 


identical information and perform the same operations to create the desired font. However, one accepts a 
LOGFONT structure to receive all the necessary information, whereas the other needs each member of the 


structure to be passed individually. Below are the declarations for each function. 


Declare Function CreateFontIndirect Lib "gdi32.dll1" Alias 
"CreateFontIndirectA" (lplf As LOGFONT) As Long 





Declare Function CreateFont Lib "gdi32.d1ll1" Alias "CreateFontA" (ByVal 
nHeight As Long, ByVal nWidth As Long, ByVal nEscapement As Long, ByVal 
nOrientation As Long, ByVal fnWeight As Long, ByVal fdwItalic As Long, 
ByVal fdwUnderline As Long, ByVal fdwStrikeOut As Long, ByVal fdwCharSet 
As Long, ByVal fdwOutputPrecision As Long, ByVal fdwClipPrecision As Long, 
ByVal fdwQuality As Long, ByVal fdwPitchAndFamily As Long, ByVal lpszFace 
As String) As Long 




















Clearly, the use of structures greatly simplifies the use of some functions, especially when large amounts of 
information need to be passed to or from the function. Notice that when a structure is passed to a function, it is 
always passed ByRef. Structures are generally easy to use in the API and should not cause any great problem 
using them. 


<< Back to Part 3 | Contents of Introduction | Forward to Part 5 >> 
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Using API Callback Functions 


Introduction 


Callback functions are a powerful tool, giving great flexibility to some API functions. A callback function allows your 
program to build its own routines to handle events generated by the API functions themselves. Your program must contain 
any callback functions it wishes to use, because Windows does not define any "default" callback functions. 


Usage of Callback Functions 


Callback functions are used when it is necessary that the program calling the API function handle some of the work. The 
most common examples of callback functions occur in enumeration. During an enumeration, the invoked API function 
locates all objects which fit the desired category. For example, when using EnumWindows to enumerate all windows 
currently open, the API function obtains a handle to each window it finds. However, the API function does not know what to 
do with all the handles it finds. This is where the callback function comes in. 





Callback functions typically process some sort of data during the middle of a call to an API function. Continuing the 
example, EnumWindows itself will call the program-defined callback function you specify and give it the handles, one at a 
time, that it finds. It is up to the callback function to decide to do whatever it wants with those handles. Whenever the 
callback function is finished, it is given its next handle until either all windows have been enumerated or the callback 
function instructs Enum Windows to stop. 








Of course, enumerations are only one case where callback functions might be used. They can also be used to set up a message 
handler routine for an object such as a window. This allows a program to define its own custom message handling routines 
for some messages, passing the ones it ignores to the default handler used by Windows. Even more uses for callback function 
are possible. Generally, an API function will require an associated callback function whenever it must leave the 
implementation of some necessary task to the program calling the API function. 


Callback Functions in Visual Basic 


You may recall that in an earlier page of this series, I mentioned that Visual Basic has no explicit usage of pointers. I lied. 
Visual Basic does in fact have a single operator -- the AddressOf operator -- which allows the programmer to access one type 
of pointer. The AddressOf operator is absolutely necessary in order to use a callback function. Unfortunately, since 
AddressOf was first introduced in Visual Basic 5.0, any earlier versions of Visual Basic have no way whatsoever of using 
callback functions. No other workaround exists. In fact, the AddressOf operator was developed specifically to allow Visual 
Basic programs to use callback functions! 


The AddressOf operator has very limited uses. Most importantly, it can only return the address of a function defined by your 
program. This function must be Public and be defined in a module (not a form). Furthermore, the AddressOf operator itself 
can only be used inside of the argument list of a call to a function; it cannot be used any other time. In use, the AddressOf 
operator has the following syntax: 
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AddressOf function_name 





function_name is the name of the function to get the address of. AddressOf returns a pointer to the specified function. Any 
callback-using API function needs a pointer to the callback function in order to invoke it. Keep in mind that the AddressOf 
operator itself does not call the function given to it, and it does not take the argument list of that function either. It merely 
returns a pointer to where that function appears in memory. 


Example 


Below is a small example demonstrating how a callback function might be used. This example enumerates all of the windows 
currently open. For any windows which have a nonempty caption, the callback function prints that caption in the Debug 
window. You'll notice that the "meat" of this example is in the callback function itself. The other part of the code only serves 
to call the proper API function. Also note how various sections of the example must be copied into different places of a 
Visual Basic program. 


Display the title bar text of all top-level windows. This 

task is given to the callback function, which will receive each handle 
individually. 

' Note that if the window has no title bar text, it will not be displayed (for 
clarity's sake). 








' xxx Place this code in a module. This is the callback function. *** 


' This function displays the title bar text of the window identified by hwnd. 
Public Function EnumWindowsProc (ByVal hwnd As Long, ByVal lParam As Long) As Long 
























































Dim slength As Long, buffer As String ' title bar text length and buffer 
Dim retval As Long ' return value 
Static winnum As Integer ' counter keeps track of how many windows have been 
enumerated 
winnum = winnum + 1 ' one more window enumerated.... 
slength = GetWindowTextLength (hwnd) + 1 ' get length of title bar text 
If slength > 1 ' if return value refers to non-empty string 
buffer = Space(slength) ' make room in the buffer 
retval = GetWindowText (hwnd, buffer, slength) " get title bar text 
Debug.Print "Window #"; winnum; " : "; ' display number of enumerated window 
Debug.Print Left (buffer, slength - 1) ' display title bar text of enumerated 
window 
End If 
EnumWindowsProc = 1] ' return value of 1 means continue enumeration 





End Function 





' *** Place this code wherever you want to enumerate the windows. *** 
Dim retval As Long ' return value 








Use the above callback function to list all of th numerated windows. Note that 
lParam is 

' set to 0 because we don't need to pass any additional information to the function. 
retval = EnumWindows (AddressOf EnumWindowsProc, 0) 























http://216.26.168.92/vbapi/articles/intro/part05.html (2 of 3) [9/1/2002 6:23:58 PM] 


Windows API Guide: Using API Callback Functions 
Footnote: Working Around AddressOf's Limitations 


The AddressOf operator is only valid when it appears in the argument list of a function when it is called. However, 
sometimes it is necessary to set a data member of a structure to the address of a function. Some API functions include a 
pointer to a callback function as part of the structure passed to them. However, something like the following will not work 


properly: 


Dim ofn As OPENFILENAME 
ofn.lpfnHook = AddressOf AnyFunctionName 





Although you need to set ofn.lpfnHook to a pointer to the function AnyFunctionName, the AddressOf operator will cause an 
error. So how do you get the information into the structure's data member? Remember that AddressOf is valid only inside of 
a function call -- a function call in general, not necessarily a call to an API function! The trick is to create some sort of 
"dummy" function such as the one below. 








Public Function DummyFunc (ByVal pointer As Long) As Long 
DummyFunc = pointer 
End Function 


This function simply returns whatever value was passed to it originally. So what is the purpose of this function? Take a look 
at the code below, which is a modified form of the original attempt to use AddressOf with a structure: 


Dim ofn As OPENFILENAME 
ofn.lpfnHook = DummyFunc (AddressOf AnyFunctionName) 











This code executes perfectly! AddressOf here is valid because it appears in the argument list to DummyFunc. Since 
DummyFunc just returns whatever was passed to it, the end result is that ofn.lpfnHook is effectively set to Addressof 
AnyFunctionName. The dummy function acts as a tool to work around AddressOf's limitations. You'll need to use 
DummyFunc or a similarly defined function whenever you want to use AddressOf outside of a function call. 


<< Back to Part 4 | Contents of Introduction | Forward to Part 6 >> 
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Advanced API Topics 


Introduction 


As I mentioned earlier, Visual Basic hides some of the more difficult (and therefore powerful) concepts in programming 
from you. Its rationale is noble -- to make Visual Basic a simpler language to use -- and it often pays off. However, this 
simplicity becomes a liability when using the Windows API. The most obvious case here is pointers. Because Visual Basic 
almost always hides the pointers it uses from the programmer, using them in API functions can at times be difficult. 


This final page reveals some of what Visual Basic hides from you during API-based programming. You won't find very 
much of this in Visual Basic's documentation; I learned most of this from experience and frustration. Nevertheless, a firm 
understanding of the following material is crucial for mastering the most complex of API functions. 


The Truth About ByVal and ByRef 


Earlier in this series, the superficial meanings of ByVal and ByRef were defined. However, in reality something somewhat 
more sinister is happening. You already know that Windows is a 32-bit operating system. Well, it just so happens that every 
parameter passed to any API function is a 32-bit integer. 


"Wait just a minute,” I'm sure you're saying right now. "You can too pass other things as parameters to API functions. Why, 
some functions take strings as parameters; others take byte arrays and structures. What do you mean, only 32-bit integers?" 
Well, behind the scenes, only 32-bit integers are being passed to the API functions. Although it looks like something else in 
your Visual Basic code, it does that to make things easier for you, which does in fact help most of the time. 


Once again, ByRef literally means "By Reference." That "reference" is in reality a 32-bit pointer. That's right, Visual Basic 
is actually passing a 32-bit pointer to the object passed by reference. That structure isn't being passed -- only a pointer to it 
is. The same thing happens with anything else passed ByRef; that's why API functions can only edit your program variables 
when they are passed ByRef (except for strings). By using the pointer, the API function is able to access the variable itself 
to read or change. 


The ByVal keyword is pretty much what it appears to be. It does pass the actual value of the parameter to the function. 
Again, that's why ByVal-passed variables (except for strings) cannot be edited by the function; the API function has no way 
to access the variable itself. API functions require ByVal whenever they do not need to modify the value of a 32-bit integer. 


The Truth About Strings 


You probably noticed that, in the above section, I kept making an exception for strings. While strings are always passed 
ByVal, the API function is always able to modify them freely. On the surface, it looks like this is impossible: nothing 
passed ByVal can be modified, right? But remember that every "real" parameter passed to an API function is a 32-bit 
integer. Strings passed ByVal aren't 32-bit integers, right? 
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It turns out that strings are much more sinister than you can imagine. It all stems from the differences between Visual Basic 
and C++. In C++, there is no "string" data type. Instead, an array of byte-long elements (of the "character data type) is used 
to represent a string, each element in the array storing a single letter. The final element in the array is equal to 0, the null 
character. Whenever these pseudostrings are used, especially in parameter passing, a pointer to the first element is used. 
This pointer effectively references the entire string: everything from the pointed-at element to the terminating null. 


Why does any of this matter? Remember that the Windows API is written in C++ and therefore uses the C++ style of string. 
Visual Basic is forced to use the Windows API to execute virtually all of its string operations (implicitly through Visual 
Basic's intrinsic functions). This forces Visual Basic to internally use the C++ style strings all the time while providing the 
programmer with its own easier-to-use string data type. 


In reality, the Visual Basic String data type is actually a special form of the Long data type! Throughout the entire Visual 
Basic command set, the programming language recognizes the difference between a String and a Long and acts accordingly. 
(For example, the Len function returns the number of bytes in the actual string, not the length of the "real" variable.) And 
what does this covert 32-bit integer hold? Naturally, it holds a pointer to the beginning of the actual string! This is why 
strings must always be passed ByVal: the string itself is not passed, but the pointer to it is. Similar reasoning explains why 
API functions can edit these strings despite having been passed ByVal. 


Don't believe what I just said? I can prove it to you. Consider the following structure: 
Public Type MYSTRUCT 
svar As String 
End Type 
This structure has a single data member: a variable-length string. Now ask yourself, what is the size of the structure? Does it 
depend on the content of the string? Or is it a constant value? Try running the following code and you'll discover the 


answer: 


Dim st As MYSTRUCT 











st.svar = "This is a line of text." 
Debug.Print "Size of structure is"; Len(st) 
st.svar = "Hello, world!" 





Debug.Print "Size of structure is"; Len(st) 





Run this code and you'll notice that both times, the size of the structure is reported to be 4. This is in fact the size in bytes of 
a 32-bit integer! The structure does not actually store a string. Instead, it stores a 32-bit pointer to the string. When you 
think about it, there's no other way to implement a variable-length string inside a structure. If the string truly were 
embedded in the structure, its entire contents would have to be rearranged every time the length of the string changed. 


But what about fixed-length strings? It turns out that they are what they claim to be; they are not pointers. Try changing the 
data member in MYSTRUCT to the data type "String * 40" and run the example. Both times, the reported size will be 40. 
For fixed-length strings in a structure, the contents of the string are in fact embedded in the structure. However, this holds 
only for structures. If you define a fixed-length string outside a structure, it will still actually be a pointer to a string and 
must be passed ByVal to any API function. 


Has all of this been confusing? It probably has, since you learned the truth about one of the great deceptions Visual Basic 
makes. This information really doesn't apply to anything else besides API function programming. Nevertheless, this 
realization should explain the curious use of ByVal for strings. Besides, this advanced information will give you a better 
understanding about what you're typing into your program. 
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The ByVal Keyword and CLng() Function 


The ByRef method of parameter passing is often used when a pointer to some object is needed. However, in some cases, 
you wish to specify no object at all. For example, with some API functions, if you do not use an optional feature which 
requires a certain structure, passing that structure anyway will cause the function to fail. You need to somehow pass 
"nothing" for a ByRef parameter. 


The way to accomplish this is to make use of the ByVal keyword. Placing the ByVal keyword immediately before the 
desired parameter, that parameter will be passed by value regardless of what appears in the function's declaration. Then you 
are able to simply pass 0 as the parameter, effectively giving a null pointer to the function. But what if that parameter is not 
a Long data type? Change the declaration to make that parameter's data type Any! But then, when you pass a null pointer, 
you must use the expression ByVal CLng(0). 


Why "ByVal CLng(0)"? As the previous paragraph stated, ByVal is necessary to pass 0 for the parameter, instead of a 
pointer to where that 0 is stored in memory (and that pointer would not be 0). CLng() is a data type conversion function 
which converts a number into the Long data type. If you did not include the call to CLng(), Visual Basic would not know 
which data type the 0 is. Since the function declaration, reading As Any for that parameter, would not offer any help, it 
would probably try to pass it as a regular Integer or some other non-32-bit integer. But since API functions only accept 32- 
bit integers for parameters, a fatal error would arise. Therefore, using "ByVal CLng(0)" assures that a fully 32-bit 0 is being 
passed to the function, and everything will work perfectly. 


For an example of ByVal CLng(0) in action, look at the following example: 


" Read both a Long (32-bit) number and a String from the file 

' C:\Test\myfile.txt. Notice how the ByVal keyword must be used 
' when reading a string variable. 

Dim longbuffer As Long ' receives long read from file 

Dim stringbuffer As String ' receives string read from file 

Dim numread As Long ' receives number of bytes read from file 
Dim hFile As Long ' handle of the open file 

Dim retval As Long ' return value 











' Open the fil for read-level access. 

hFile = CreateFile("C:\Test\myfile.txt", GENERAL_READ, 

CLng (0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0) 

If hfile = -1 Then ' the file could not be opened 

Debug.Print "Unable to open the file it probably does not exist." 
End ' abort the program 

End If 














Hy 


‘ILE SHARE READ, ByVal 












































' Read a Long-type number from the file 
retval = ReadFile(hFile, longbuffer, Len(longbuffer), numread, ByVal CLng(0) ) 











If numread < Len(longbuffer) Then ' EOF reached 

Debug.Print "End of file encountered -- could not read the data." 
Else 

Debug.Print "Number read from file:"; longbuffer 
End If 





' Read a 10-character string from the file 
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stringbuffer = Space(10) ' make room in the buffer 
retval = ReadFile(hFile, ByVal stringbuffer, 10, numread, ByVal CLng(0)) 
































If numread = 0 Then ' EOF reached 

Debug.Print "End of file encountered -- could not read any data." 
ElseIf numread < 10 Then ' read between 0 and 10 bytes 

Debug.Print "Incomplete string read: "; Left (stringbuffer, numread) 
Else 

Debug.Print "String read from file: "; stringbuffer 
End If 





" Close the file. 
retval = CloseHandle (hFile) 








Remember: if you ever have to pass a "null pointer" (1.e., a value of 0 for a ByRef) to a function, you must change that 
parameter's data type in the declaration to Any, in case it is something different. If that parameter is not ByVal according to 
the declaration, then the ByVal keyword must be used explicitly in the call to the function. Finally, you must make use of 
the CLng() conversion function to force the 0 to be fully 32 bits in length. 


Getting Pointers to Other Objects 


Sometimes, an API function will demand a pointer to some sort of object, in which case you must find a way to obtain the 
necessary pointer. Sadly, the AddressOf operator only works with application-defined functions, so it cannot provide a 
pointer to a structure or other object. So what can you do? 


Actually, there is no way in Visual Basic to get a pointer to any object. Instead, you should create a memory block of the 
necessary length and copy the object (often a structure) into that block. By using the GlobalAlloc and GlobalLock 
functions, both a handle and a pointer to this memory block can be obtained. Then, when calling the necessary API 
function, you can simply use a pointer to the memory block instead of one to the original object. Since the memory block 
holds a copy of the data (generated via the Istrcpy function for strings, or the CopyMemory function for all other objects), 
there is effectively no difference between it and the original object. After using the block, it should be freed using the 
GlobalUnlock and GlobalFree functions as necessary. 





The easiest way of learning how to create and manipulate these pure memory blocks is to examine an example of it in use. 
The following example opens the Choose Font common dialog box. The CHOOSEFONT_TYPE structure requires a 


pointer to a LOGFONT structure as one of its data members. This is done by using a memory block (referenced via hMem 
and pMem) to hold a copy of the structure. The structure's contents is initially copied into the memory block, and later the 
block is copied back to the structure in case any alterations were made to its contents. 


' Display a Choose Font dialog box. Print out the typeface name, point size, 

' and style of the selected font. More detail about topics in this example can be 
found in 

" the pages for CHOOSEFONT TYPE and LOGFONT. 

Dim cf As CHOOSEFONT TYPE ' data structure needed for function 

Dim lfont As LOGFONT ' receives information about the chosen font 

















Dim hMem As Long, pMem As Long ' handle and pointer to memory buffer 
Dim fontname As String ' receives name of font selected 
Dim retval As Long ' return value 
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' Initialize the default selected font: Times New Roman, regular, black, 12 point. 
' (Note that some of that information is in the CHOOSEFONT_TYPE structure instead.) 
lfont.1lfHeight = 0 ' determine default height 

lfont.1lfWidth = 0 ' determine default width 

lfont.1fEscapement = 0 ' angle between baseline and escapement vector 
lfont.1fOrientation = 0 ' angle between baseline and orientation vector 
lfont.1lfWeight = FW_NORMAL ' normal weight i.e. not bold 

lfont.1lfItalic = 0 ' not italic 

lfont.1lfUnderline = 0 ' not underline 

lfont.1fStrikeOut = 0 ' not strikeout 

lfont.1lfCharSet = DEFAULT_CHARSET " use default character set 
lfont.1fOutPrecision = OUT_DEFAULT_PRECIS ' default precision mapping 
lfont.1fClipPrecision = CLIP_DEFAULT_PRECIS ' default clipping precision 
lfont.1lfQuality = DEFAULT_QUALITY ' default quality setting 
lfont.1fPitchAndFamily = DEFAULT_PITCH Or FF_ROMAN ' default pitch, proportional 
with serifs 

lfont.1fFaceName = "Times New Roman" & vbNullChar ' string must be null-terminated 











" Create the memory block which will act as the LOGFONT structure buffer. 
hMem = GlobalAlloc(GMEM MOVEABLE Or GMEM_ ZEROINIT, Len(lfont) ) 








po 





























pMem = GlobalbLock (hMem) ' lock and get pointer 
CopyMemory ByVal pMem, lfont, Len(lfont) " copy structure's contents into block 








' Initialize dialog box: Screen and printer fonts, point size between 10 and 72. 








cf.1StructSize = Len(cf) ' size of structure 

cf.hwndOwner = Forml.hWnd ' window Forml is opening this dialog box 

cf.hdc = Printer.hDC ' device context of default printer (using VB's mechanism) 
cf.lfLogFont = pMem ' pointer to LOGFONT memory block buffer 

cf.iPointSize = 120 ' 12 point font (in units of 1/10 point) 




















cf.flags = CF_BOTH Or CF_EFFECTS Or CF_FORCEFONTEXIST Or CF_INITTOLOGFONTSTRUCT Or 
CF_LIMITSIZE 















































cf.rgbColors = RGB(0, 0, 0) ' black 
cf.lCustData = 0 ' we don't use this here... 
cf.lpfnHook = 0 ' ...or this... 
cf.lpTemplateName = ""  ' ...0or this... 
cf.hInstance = 0 ' ...or this... 
cf, lpsz5tyle =" F se sor this 
cf.nFontType = REGULAR_FONTTYPE ' regular font type i.e. not bold or anything 
cf.nSizeMin = 10 ' minimum point size 
cf.nSizeMax = 72 ' maximum point size 
' Now, call the function. If successful, copy the LOGFONT structure back into the 
structure 
' and then print out the attributes we mentioned earlier that the user selected. 
retval = ChooseFont (cf) ' open the dialog box 
If retval <> 0 Then ' success 
CopyMemory lfont, ByVal pMem, Len(lfont) " copy memory back 





" Now make the fixed-length string holding the font name into a "normal" string. 
fontname = Left (lfont.1lfFaceName, InStr(lfont.1lfFaceName, vbNullChar) - 1) 

' Display font name and a few attributes. 

Debug.Print "FONT NAME: "; fontname 
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End If 








' Deallocate the memory bl 


£ Lionta] 
If lfont.] 
IE TROnt «J 


Debug. Print 
Debug.Print "FONT 
I LfWeight 





"FONT SIZE (points):"; cf.iPointSize / 10 ' in units of 1/10 point! 











Debug.Print 


' end the J] 


SLVLE CS) 2. Ty 

>= FW_BOLD Then Debug.Print "Bold "; 
If lfont.lfItalic <> 0 Then Debug.Print "Italic "; 
lfUnderline <> 
lfStrikeOut <> 

















0 Then Debug.Print "Underline "; 
0 Then Debug.Print "Strikeout"; 
line 











lock we created earlier. Note that this must 


" be done whether the function succeeded or not. 





retval = 


obal 





Unlock (hMen 








retval = 





Gl 
Gl 





obal 





Free (hMem) 





<< Back 


n) ' destroy pointer, unlock block 
' free the allocated memory 
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